Convert documentation to MyST Markdown and new theme

[choldgraf]

This is a meta-issue to track conversion of documentation syntax to use MyST Markdown. It may grow or shrink as more focused issues pop up during initial conversion so I'll track them here.

• Initial conversion attempt via MyST parser (Initial update to use MyST Parser #1192)
• Convert over eval-rst blocks into MyST markdown (Updating eval-rst blocks to MyST #1220, Updating eval-rst blocks to myst directives #1221, build: Convert eval-rst directives #1247)
• Check that we are using references to headers / labels rather than hard-coding headers in URLs md: Use (and fix) auto-generated header anchors #1253
• Convert the theme to either Sphinx Book Theme or the PyData theme: Updating to PyData Sphinx Theme #1254
• Modifications to theme as-needed for the OCDS docs
• Content modifications that take advantage of theme/myst features (e.g., sphinx-panels)
• Updates to the contributing content documentation to highlight any new functionality

After this is mostly done

Note - Chris is not sure if the following are in scope for him or not...he suspects somebody else will be more efficient in doing it than he is

• Create sub-theme to replace search page like https://github.com/open-contracting/standard_theme/blob/open_contracting/standard_theme/search.html and https://github.com/open-contracting/standard_theme/blob/open_contracting/standard_theme/static/js/search.js
• Update ocds-index Update crawler for new Sphinx theme ocds-index#6

[choldgraf]

Also note - I'm going to prefix all of these issues with [MyST] to help differentiate them from others, since I cannot add tags etc myself.

[choldgraf]

@jpmckinney do you prefer to have one mega-PR that does all of the changes at once, or is it OK to break this into several smaller PRs that get merged over time?

[jpmckinney]

I've changed your role to Maintain, so you should be able to create/add labels. An issue prefix is also fine.

I have no preference in terms of PR size. For larger PRs, I sometimes read one commit diff at a time when reviewing.

[jpmckinney]

Follow-up for this issue:

• Update selector(s) in util/add_translation_notes.py

Small cleanup that can be done in later PRs:

• Build with sphinx-build -nW --keep-going -q -b dirhtml $(DOCS_DIR) $(BUILD_DIR)/en once warnings are cleared
• Change some eval-rst to block-level directives https://myst-parser.readthedocs.io/en/latest/using/intro.html#block-level-directives-with-myst-markdown
• Check links to headings

After theme change, follow-up to replicate search features:

• Create sub-theme to replace search page like https://github.com/open-contracting/standard_theme/blob/open_contracting/standard_theme/search.html and https://github.com/open-contracting/standard_theme/blob/open_contracting/standard_theme/static/js/search.js
• Update ocds-index Update crawler for new Sphinx theme ocds-index#6

[choldgraf]

Hey @jpmckinney - I've updated the top comment with a few more of the to-dos that we discussed. I think that a lot of the eval-rst blocks are converted, and I'm wondering what you'd prefer that we prioritize moving forward. E.g., do you prefer that we finish up the MyST conversion to 100%, or better to try out new themes etc?

[jpmckinney]

I think better to try out new themes. And yes, I'll do the two search-related bullets :)

[choldgraf]

@jpmckinney we just released a new version of the PyData theme: https://github.com/pydata/pydata-sphinx-theme/releases

I think that this should make it a bit easier to customize and such. When trying out a new theme for these docs, would you like to try that (because it is a topbar-based theme) or start with the Sphinx Book Theme (https://sphinx-book-theme.readthedocs.io/) ?

My intuition is that if you'd like a top-bar for navigation eventually, then it will be easier to start with the PyData theme and customize, rather than start w/ the Book theme and add a top-bar. Strong preferences?

[jpmckinney]

Thanks for the explanation and updates! Let's go with the PyData theme 👍

[jpmckinney]

See open-contracting/standard_profile_template#37