Page Comparison

...

In-Progress PRs (Reverted/Closed)

The following BD-34 work was either reverted or closed until we can come back to this.

...

Other Developer Documentation Notes

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.

    • UPDATE: This 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?

Repo 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?

Other resources

• Google Analytics data for Readthedocs traffic

• Developer Documentation and Training Survey Results - 2021-Jan

• Toggles and Settings Documentation

• BD-34 Dev Docs Stand-up Notes (Google Doc)

  • Includes many useful notes and background for any future effort.

...