Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Switch to Sphinx/reCommonMark for HTML documentation generation #1451

Closed
nodiscc opened this issue May 1, 2020 · 2 comments · Fixed by #2025
Closed

Switch to Sphinx/reCommonMark for HTML documentation generation #1451

nodiscc opened this issue May 1, 2020 · 2 comments · Fixed by #2025
Assignees
@nodiscc
Labels
documentation tools developer tools
Milestone
0.13.0

Comments

@nodiscc
Copy link
Member

nodiscc commented May 1, 2020

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:

  • syntax checks (typos, dead internal links/references)
  • tooling (Makefile, Tox)
  • flexible table of contents management
  • integrations with diagramming tools like Graphviz/dot and PlantUML
  • builders for HTML, LaTeX, PDF, EPUB, etc.

The switch to recommonmark + sphinx can easily be done, here is a sample working config:
@nodiscc nodiscc added documentation tools developer tools labels May 1, 2020
@nodiscc nodiscc added this to the backlog to the future milestone May 1, 2020
@nodiscc nodiscc self-assigned this May 1, 2020
@nodiscc nodiscc mentioned this issue May 1, 2020
Open
@nodiscc
Copy link
Member Author

nodiscc commented Feb 2, 2021

No longer blocked

@nodiscc nodiscc modified the milestones: backlog to the future, 1.1.0 Feb 2, 2021
@nodiscc nodiscc modified the milestones: 1.1.0, 1.0.0 May 25, 2021
nodiscc added a commit to nodiscc/Shaarli that referenced this issue Sep 25, 2023
@nodiscc
replace mkdocs with sphinx/myst-parser for HTML documentation generation
a51ce1d 
- fixes shaarli#1451
nodiscc added a commit to nodiscc/Shaarli that referenced this issue Oct 4, 2023
@nodiscc
replace mkdocs with sphinx/myst-parser for HTML documentation generation
164e480 
- fixes shaarli#1451
nodiscc added a commit to nodiscc/Shaarli that referenced this issue Oct 5, 2023
@nodiscc
replace mkdocs with sphinx/myst-parser for HTML documentation generation
db15322 
- 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
@nodiscc nodiscc mentioned this issue Oct 5, 2023
Merged
@nodiscc
Copy link
Member Author

nodiscc commented Oct 5, 2023 •
edited
Loading

PR at #2025 (recommonmark was deprecated in favor of myst-parser readthedocs/recommonmark#221)

@nodiscc nodiscc modified the milestones: 1.0.0, 0.13.0 Oct 5, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@nodiscc nodiscc

Labels
documentation tools developer tools
Projects
None yet
Milestone
0.13.0
1 participant
@nodiscc