Page Comparison

...

• Publishing code repo docs to Readthedocs

  • May need to update Publish Documentation on Read the Docs

  • If readthedocs admin page becomes unmanageable, will need tooling using API like Ned’s spreadsheet of readthedocs projects from a Hackathon.

  • How should an owner decide when this is warranted? Is it always warranted?

  • We don’t have a documented best practice for links that work from inside github and readthedocs.

    • Possible solution: https://github.com/readthedocs/readthedocs.org/issues/2926

  • The cookiecutter does not have a great default readthedocs outline.

    • See edx-toggles and edx-django-utils for possible enhancements.

    • Related: We don’t have a best practice for including docs from inside the repo in the main published docs.

      • See edx-django-utils docs/monitoring/README.rst for a temporary solution and pointers to other solutions.

• Fix Sphinx theme

  • UPDATE: See https://github.com/openedx/edx-sphinx-theme/issues/184

  • https://github.com/edx/edx-sphinx-theme has several issues:

    • Many styling issues for header levels in sidebar (indent, size, twisty, selection)

      • Worse for levels 3 and 4

    • Menu is broken on mobile.

    • Styles are easy to break. See (temporary) docutils constraint due to styling issue.

      • TODOUPDATE: Remove constraint once we have a solutionThis constraint was removed.

  • Potential solutions:

    • Switch to using a maintained Sphinx theme.

      • A logo can be configured, if that was a past sticking point.

    • Updating edx-sphinx-theme with clear instructions of what theme it is based on and how to keep it in sync with updates, and what features are custom to this theme.

  • Ownership and resourcing?

• open-edx-proposals maintenance

  • make requirements doesn’t work until after you have sphinx installed.

  • make develop complains about a missing directory. Should this even be used?

  • Should the Sphinx Makefile be separated from the main Makefile, like in edx-developer-docs? Or, does someone know how to make this work?

...