Open jpmckinney opened 3 years ago
Hi 👋🏼 . I found this issue while browsing for Read the Docs issues and I wanted to comment some things 😄
Top-level static files like standard.open-contracting.org/schema If hosted on ReadTheDocs, I think we'd have to use redirects, or release these separately.
Subprojects. If hosted on ReadTheDocs, subprojects can be used. This allows searching across subprojects. However, we'd have a
/projects/
path component instead of/profiles/
.
This limitation was removed and that /projects/
prefix can be changed now.
Version switcher Add version dropdown (for other versions of the docs) pydata/pydata-sphinx-theme#23. If hosted on ReadTheDocs, this is natively supported, though not sure how this works for custom themes.
There is a completely new beta approach to this version switcher that's called "addons". Currently, the version switcher is added at the bottom-right of the page. You can see an example at https://test-builds.readthedocs.io/en/latest/
Also, we are working on a way to heavily customize the version switcher from the Sphinx theme itself by subscribing to a JavaScript CustomEvent
and manipulate the Read the Docs data as wanted. You can see an example of this implementation at https://github.com/readthedocs/sphinx_rtd_theme/pull/1526. I'd love your feedback about this approach in case you are considering integrating the version switcher in your custom theme.
Compiling non-Sphinx catalogs. We can maybe add some code in conf.py if we don't find another way.
I understand you need to run custom commands for non-Sphinx catalogs. Read the Docs now supports this by using build.jobs
or build.commands
config keys, depending on your needs. Documentation at https://docs.readthedocs.io/en/latest/build-customization.html
Banners: RTD injects an admonition as HTML, e.g. csvkit.readthedocs.io/en/0.9.0 We should test it with MyST.
This was also rewritten with the new addons approach and they work on any Sphinx theme, even on different documentation tools, like Docusaurus: https://test-builds.readthedocs.io/en/docusaurus/
Search: readthedocs-sphinx-search.readthedocs.io/en/latest/customization.html#custom-search-input but Support
readthedocs-sphinx-search
pydata/pydata-sphinx-theme#202
The readthedocs-sphinx-search
extension is deprecated in favor of the new addons approach as well 😄 . Now, if you click on the input from the flyout out shown at the bottom-right you will get a new and better version of the "search as you type" feature.
If you want to trigger the "Read the Docs Search addon" when clicking on any other input (e.g. the default search input that Sphinx uses) you can add a small JavaScript code to trigger the correct event on input.focus()
.
Version/locale flyout: Works, but can use improvement: ReadTheDocs version selector always on top for mobile displays pydata/pydata-sphinx-theme#194 How to activate the RTD flyout menu? pydata/pydata-sphinx-theme#327 See also Make our documentation page APIs more user friendly readthedocs/readthedocs.org#7748
As I mentioned before, we are working on giving the theme authors access to all the data in a JSON structure so they can integrate nicely with the theme as shown in this PR: https://github.com/readthedocs/sphinx_rtd_theme/pull/1526. Again, feedback welcome.
Let me know if this helps you with the decision about whether or not using Read the Docs for your docs 🎉
Thank you for this information!
Related: https://github.com/pradyunsg/sphinx-basic-ng/issues/12#issuecomment-1809973724
If we switch to DocSearch https://github.com/open-contracting/ocds-index/issues/7, the deployment process would then just be copying the built pages to the server. We still need our own hosting for:
/projects/
path component instead of/profiles/
.We currently need our own build system for:
current_lang
logic for linking to translated schema and codelists. OCDS for PPPs doesn't use it though - in conf.py, it instead writes these files to both the language's root and to a_static
path that is ignored by git.util/add_translation_notes.py
. We should hook this into Sphinx using thebuild-finished
event instead: https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-eventsIf we address all the above, it could be possible to host on ReadTheDocs or elsewhere. To opt-out of ads, see https://readthedocs.org/accounts/gold/
For older instructions on setting up ReadTheDocs: https://ocds-standard-development-handbook.readthedocs.io/en/latest/profiles/technical/integrations.html
If using ReadTheDocs, we should configure:
We can also eliminate
test_common.py
as we can trust that the build, search and language switcher work. (Note: When we switch to sphinx-inline-tabs instead of our custom jsoninclude JS, we can also eliminatetest_docs.py
.)I think the main question is how well ReadTheDocs' features are supported when using a custom theme. Docs for integration with:
Note that the version/locale switchers need to be updated for the new theme anyway https://github.com/open-contracting/standard/pull/1254#issuecomment-822971743. If we decide to switch to RTD, we can avoid doing this work twice.