Switch to Sphinx/reCommonMark for HTML documentation generation #1451
Comments
|
No longer blocked |
nodiscc
added a commit
to nodiscc/Shaarli
that referenced
this issue
Sep 25, 2023
nodiscc
added a commit
to nodiscc/Shaarli
that referenced
this issue
Oct 4, 2023
nodiscc
added a commit
to nodiscc/Shaarli
that referenced
this issue
Oct 5, 2023
- fixes shaarli#1451 - tools/.gitattributes: exclude doc/conf.py and doc/requirements.txt from zip exports - tools/doc/sphinx: suppress myst.xref_missing warnings caused by executablebooks/MyST-Parser#564 - dockerfile: use makefile/sphinx instead of mkdocs to build HTML documentation - dockerfile: add bash to the docs build container (make: bash: No such file or directory) - tools/doc/readthedocs: force use of python 3.11 (readthedocs ERROR: No matching distribution found for sphinx==7.1.0) - tools/doc/readthedocs: add all required configuration variables https://docs.readthedocs.io/en/latest/config-file/v2.html#build-os - tools/doc/readthedocs: override build commands to allow the source directory to be different from the conf.py directory (https://docs.readthedocs.io/en/stable/config-file/v2.html#build-commands, readthedocs/readthedocs.org#1543) - tools/doc/readthedocs: manually set output directory (readthedocs ERROR: No _readthedocs/html folder was created during this build.) - doc: replace all references to mkdocs with sphinx
|
PR at #2025 (recommonmark was deprecated in favor of myst-parser readthedocs/recommonmark#221) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Hi,
Documentation in multiple languages can be managed using the Sphinx documentation engine, which provides internationalization features:
The translation files use the Gettext format and can be edited with Poedit or sphinx-intl
As Sphinx is ReadTheDocs' canonical engine, internationalization is supported there as well:
This would require porting the documentation to Sphinx (which we already use for the Python API client) and either switching to CommonMark (Markdown with batteries included) or reStructuredText.
IMO this would be interesting as Sphinx has a number of advantages over MkDocs:
The switch to recommonmark + sphinx can easily be done, here is a sample working config:
The text was updated successfully, but these errors were encountered: