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.

• [x] Initial conversion attempt via MyST parser (https://github.com/open-contracting/standard/pull/1192)
• [x] Convert over eval-rst blocks into MyST markdown (#1220, #1221, #1247)
• [x] Check that we are using references to headers / labels rather than hard-coding headers in URLs #1253
• [ ] Convert the theme to either Sphinx Book Theme or the PyData theme: https://github.com/open-contracting/standard/pull/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 https://github.com/open-contracting/ocds-index/issues/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:

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

Small cleanup that can be done in later PRs:

• [x] Build with sphinx-build -nW --keep-going -q -b dirhtml $(DOCS_DIR) $(BUILD_DIR)/en once warnings are cleared
• [x] Change some eval-rst to block-level directives https://myst-parser.readthedocs.io/en/latest/using/intro.html#block-level-directives-with-myst-markdown
• [x] 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 https://github.com/open-contracting/ocds-index/issues/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 https://github.com/open-contracting/standard_profile_template/issues/37