-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 On Tue, Dec 21, 2021 at 08:57:27PM +0100, mm wrote: > Hello all, > > in September there was a thread about migrating the documentation to another > platform, > and the silent winner was RTD. > Let me say up front: For me localization, release specific docs, automation > & easy and transparent maintenance of the documentation > are one of the most important criteria for this. > I took a closer look at RTD wtr to localisation and this is what I found > out: > > > TL;DR: > > #### > > Here is a preliminary test version of the qubes documentation as in _doc, > uploaded to the RTD, using sphinx with markdown support and transifex fake > translations: > > https://qubes-doctestrun.readthedocs.io/en/latest/README.html > > & https://qubesosgithubiotestrun.readthedocs.io/en/latest/doc.html > > > And a sample wannabe german translation at: > > https://qubes-doctestrun.readthedocs.io/de/latest/README.html > > & https://qubes-doctestrun.readthedocs.io/de/latest/doc.html > > In the bottom menu you can choose a language, specific version (right now > only different html themes, pdf, epub) > As there are issues, as explained below, one can for now browse with > dedication via specific links such as: > > https://qubesosgithubiotestrun.readthedocs.io/en/latest/developer/building/qubes-builder.html > > > & > https://qubes-doctestrun.readthedocs.io/de/latest/developer/building/qubes-builder.html > > Of course the test repos from are behind the current state for ages. > > > The longer version: > > ############# > > > There are two generators that can are used by RTD -- sphinx (reST) or mkdocs > (md). > MkDocs is perfect for Markdown, Sphinx - for restructured text, but can > parse markdown, via an extension > but there are some problems as listed below, which need to be addressed. > > ## MkDocs > > MkDocs writes with markdown and is more or less straightforward with qubes > current state of the documentation/website. > > The problem is that MkDocs does not support localization out of the box, > but through third party plugins such as [1] or [2], > which more or less defaults to the current way of localizing the website and > thus also _doc. There are also not many third party plugins for MkDocs. > And most important - localization (in RTD) is only supported for sphinx > documentation, which settles it if the docs should be moved to RTD at least > for now: > > "This feature only applies to Sphinx documentation. We are working to bring > it to our other documentation backends." See [3] > > > ## SPHINX: > > The default generator used by RTD, which supports all the features by RTD, > including localization. > > ### MYST > > To use sphinx with markdown I tried MyST > > (see [4], [5], [6]. MyST specific configuration can be seen at [7]) > > ### HTML themes > > There are some built-in themes ([8]), configuration options ([9] or [10]) > Other themes can be found at [11]. > > Or one could overwrite and customize a theme with [12] or > > by following some tutorials ( which should the way to go for Qubes I think ) > > #### BUILD > > is as simple as `sphinx-build -b html _doc/ _build/html` > > for latex: > > ``` > sphinx-build -b latex _doc/ _build/latex > cd _build/latex > make # needs latexmk > ``` > > ### LOCALIZATION > > > Localization for sphinx is done via gettext as simple as: > > > ``` > sphinx-build -b gettext . _build/gettext > ``` > > for the configuration the following options are good as per documentation: > > ``` > gettext_uuid=True > gettext_compact=False > ``` > > > > > > #### TRANSIFEX > > There is a neat way to handle transifex and sphinx. > > > Due to a problem, which I am currently trying to solve, the sample > translations are due to a transifex trick, downloaded via tx in the root > repo and manually added to the qubestranslation repo, > > which is not in an optimal state right now. > > > There is the possibility to have all the translations in one repo as in [13] > and this is also the goal. > > Problem: The problem is that for common users in RTD once a person has > imported a repository there is no way to import it again, and for different > translations, > > RTD needs different projects, that exist in RTD and are marked as > translations for the main one ... As till now I do not know how to tackle > this issue. > > > ## PANDOC > > And of course there is the option to convert all the markdown documentation > files > to restructured text (w pandoc f.x.), > which is native for Sphinx, and thus, many of the current rendering issues > should be non-existent. > > One could convert the md to rst as in > > ``` > pandoc doc.md --from markdown --to rst -s -o doc.rst > ``` > > one can view it with restview (pip install restview) > > > ## RTD problems/TODOs > > > 1. Rendering > > There are warnings that have to be adressed such as: > > ``` > /home/user/qubes/qubesos.github.io.testrun/_doc/docs/source/user/advanced-topics/awesomewm.md:22: > WARNING: Pygments lexer name 'shell_session' is not known > /home/user/qubes/qubesos.github.io.testrun/_doc/docs/source/project-security/verifying-signatures.md:150: > WARNING: 'myst' reference target not found: /support/ > /home/user/qubes/qubesos.github.io.testrun/_doc/docs/source/user/troubleshooting/vpn-troubleshooting.md: > WARNING: document isn't included in any toctree > ... > ``` > > 2. Many broken links > 3. PDF - the documentation is not being rendered correctly > 4. EPUB - the documentation is not being rendered correctly > 5. Sphinx uses the Jinja templating engine for its HTML templates. Meaning > for files like > > https://github.com/maiska/qubes-doc.testrun/blob/49253a1f5a24a9a9f5c1c42e2395ca494a1e4b4b/developer/general/style-guide.md > > > this is the result: > https://qubes-doctestrun.readthedocs.io/de/latest/developer/general/style-guide.html > > > I have not found a converter from liquid to jinja, so there should be > another solution > > 6. External files: can be just listed in the doc.md and the markdown files > can be deleted. But the redirects are to be handled > 7. Warning: RTD is somewhat buggy if one pushes immediately one after > another several branches for one project that are activated > 8. Find out how to handle multiple translations with one repo in RTD > 9. Uploading to transifex problem (wip) > 10. Analytics (JS in general in RTD): script as in [14] with a RTD section > regarding this [15] > > > What are your thoughts on this?
Let me try to resurrect this thread :) First of all, thanks again for all this analysis. I think indeed RTD is the way to go. We'll have occasion to talk about details on the upcoming Qubes summit. Personally, I wouldn't exclude an option to convert documentation to ReST format, especially since we get several more features then (better internal links tracking, PDF/ePUB generation, built-in macros for notices, warnings etc, and several more). But of course this needs to be weighted against other factors like complexity of the conversion itself, or ease of use for maintainers and contributors. See you soon! > All the best, > > m > > [1] https://github.com/ultrabug/mkdocs-static-i18n > [2] https://github.com/mondeja/mkdocs-mdpo-plugin > [3] https://docs.readthedocs.io/en/stable/localization.html > [4] https://myst-parser.readthedocs.io/en/latest/ > [5] https://www.sphinx-doc.org/en/master/usage/markdown.html > [6] https://myst-parser.readthedocs.io/en/latest/sphinx/intro.html > [7] https://myst-parser.readthedocs.io/en/latest/sphinx/reference.html > [8] https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes > [9] https://www.sphinx-doc.org/en/master/usage/theming.html > [10] https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html > [11] https://sphinx-themes.org/#themes > [12] https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html > [13] https://github.com/sphinx-doc/sphinx-doc-translations > [14] > https://assets.readthedocs.org/static/javascript/readthedocs-analytics.js > [15] > https://docs.readthedocs.io/en/latest/advertising/advertising-details.html#analytics > > -- > You received this message because you are subscribed to the Google Groups > "qubes-devel" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to qubes-devel+unsubscr...@googlegroups.com. > To view this discussion on the web visit > https://groups.google.com/d/msgid/qubes-devel/f24cb2b0-9465-ef3c-c71f-afb71248ab9f%40maiski.net. - -- Best Regards, Marek Marczykowski-Górecki Invisible Things Lab -----BEGIN PGP SIGNATURE----- iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAmMSIcwACgkQ24/THMrX 1yw03Qf/c63FuOGz6zsBwRWMLabRM3JxCA05ILFu76bg3/MI68DtbiRcYEBnCekR CbvNIxTLq077X4N58HiIlsunhrln+n2eLgsD6H/ljp3ZGmbNdzfZhz2WdbWMaKjK 4dzdxEb6pUfrDqXrNOrxDOxRHBJYLR6mjr2ih211iPVaJccgIny8l8zSkWpTmG6S JmowbLeaxfNXsv00yODQ9Hv/7hTZj5xd0Kntq17FGrL9BWLFad0fVYxzZ93Dh6NI g6KgSnwWAvLqUZjQ7BSrjhbXuKUOeIHJ+luA23aqKioWHNcA9SXvtz2bUZyYVNeM Eve3568YYj12PcZIjbZH+3leDZ+EbA== =kYM7 -----END PGP SIGNATURE----- -- You received this message because you are subscribed to the Google Groups "qubes-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to qubes-devel+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-devel/YxIhzCN82osQq9VK%40mail-itl.
