Mkdocs revisit

[jive]

Starting a thread to coordinate restarting mkdocs transition, after some interest at foss4g-eu sprint (@Peter, @enockseth and @jsonsingh):

translate script

• jodygarnett/translate

@jsonsingh was looking at this during the sprint, just getting it to run with the included same project. And it was struggling a bit with regressions since the last time I used it.

The script is amusingly one big file (sorry) and is mostly search / replace regex expressions.

The script has been successfully used by a few projects now, notably docs.geonetwork-opensource.org, so it is useful just annoying.

geoserver status

• GSIP 221 · geoserver/geoserver Wiki · GitHub

  This has most of the good links at the end.

• Progress tracking spreadsheet

• jodygarnett.github.io/geoserver/

  Example converted and published by hand

things to do …

• get the translate script running locally, and converting its example project again

• setup a GitHub workflow for geosever to translate and publish to gh-pages

  This would enable folks to simplify the sphinx docs in cases where the script cannot do a very good job. A common example is our massive use of tables.

In general the production loop is to:

1. Review the before / after content
2. Make a note of any broken content in the spreadsheet
3. usually it finds problems in the rst file, such as unintended block comment, this can be fixed with PR to main brach.
4. If any consistent patterns emerge add to the update script to automate a fix.

[Peter]

Thank you Jody for kicking off this again, and to @enockseth and @jsonsingh for expressing interesting in how to help, as a fellow non-Java programmer, I believe?

Yes, ANYONE can help with the project, regardless of your programming skills. There is lots to be done, such as translating the GeoServer documentation from reStructuredText to MkDocs, or the automation thereof, or just by wearing a QA hat for a few hours.

Json and Enock, if you confirm your interest in this contribution, let’s start with the 2do list above. Does anyone else want to join the MkDocs endeavour?

Peter

[buehner]

Hi. I just came back from vacation and wanted to let you know that I am also interested to support here.

Please let me know how to help. Did anything happen here already in the past days?

[jive]

Nothing directly has happened, but I had the small insight.

We could setup a workflow on GitHub - jodygarnett/translate: Translate from sphinx-build to mkdocs-material compatible markdown to run the example project. Presently the example project is having a regression, so although you can check it out and run it is stumbling on some of the output.

So short term it is all about getting the script checked out, running it locally, and understanding the workflow.

1. It pre-processes the RST files, simplifying a bit first, and doing things processing references and doc links into relative paths. It has to scan the headings to have the correct text to use when making those kind of links.
2. It uses pandoc to translate to markdown
3. It post-processes the markdown, doing things like changing from pandoc version of admonition and warnings to mkdocs representation of admonitions and warnings