python translate script for converting site from sphinx-build to mkdocs-material

[jodygarnett]

To lower barrier of entry for documentation writing I have looked at converting documentation for an open source project from sphinx-build to mkdocs. And pandoc takes you about 90% of the way there.

I have now have a script for the other 10%: https://github.com/jodygarnett/translate

• scan rst files and build up index of anchors and references for doc and ref directives
• map directives like guilabel, menuselection, file, command to simple markdown
• map kdb directive to appropriate mkdocs representation (++control-s++)
• respecting admonitions like note, warning and friends
• fix the formatting that comes out needlessly escaped \| becomes | (without destroying code-blocks)
• figure out how to get tables from into pipe tables for mkdocs
• and more such tedious things
• todo: the next open source project I translate uses a lot of literalinclude to use sample code in the docs

bonus:

• deepl translation of markdown messes up formatting, but markdown -> html -> translate -> html -> markdown works

I am new to python so I am getting over some imposter syndrome to share here :)

[jodygarnett]

Here is an example:

• before: https://geonetwork-opensource.org/manuals/4.0.x/en/
• after: https://docs.geonetwork-opensource.org/4.2/

[jodygarnett]

Wanted to report back excellent progress:

The script was used to translate geonetwork docs with the result here:

• mkdocs: https://docs.geonetwork-opensource.org/4.2/
• sphinx-build source: https://github.com/geonetwork/doc/tree/4.0.x/source

Starting on the second major project now:

• sphinx-build: https://docs.geoserver.org/latest/en/user/installation/win_installer.html
• mkdocs: https://jodygarnett.github.io/geoserver/installation/win_installer/

[jodygarnett]

Also a second contributor @krishnaglodha starting to help out, teaching me more python as we go.

• separated out scan for block directives from processing, so code is easier to follow
• use mkdocs-include-markdown-plugin to handle rst .. include:: <file> directive
• can leave the sphinx-build files in place, and translate the markdown into a different folder
• As a result more of the script is being managed by configuration
• using mkdocs-macros-plugin to handle rst substitutions like |version| --> {{ version }}

[squidfunk]

Thanks for sharing your progress! If you plan to write this up into a blog post or something, feel free to share! You're also invited to create a guest-post on our blog!

[krishnaglodha]

@jodygarnett I'd be happy to take up the blog writing over the holidays, let;s plan call to decide content and key points. ?

[squidfunk]

Sure, you can schedule a quick call here.

[jodygarnett]

I am sure we are all on different sides of the world I am UTC−08:00 :)

@krishnaglodha I will contact you via chat to arrange a time. We should get a "QuickStart" or something for folks to try out the script.

[jodygarnett]

@krishnaglodha is you are still in the mix I just documented the mkdocs.yml example and did not generated. Did you still have the generation code you were working on?

I think getting basic output from nothing would be a good 1.0 target.

[jodygarnett]

Documentation now available: https://jodygarnett.github.io/translate/ (based on migration of sphinx-build example)

[squidfunk]

Thanks for sharing! cc @alexvoss

[jodygarnett]

Now available https://pypi.org/project/mkdocs-translate/

[squidfunk]

Awesome, thanks for sharing!