Going to run an experiment tomorrow and have written it up as a proposal to protect the innocent:
- https://github.com/geotools/geotools/wiki/MkDocs - https://osgeo-org.atlassian.net/browse/GEOT-7466 If successful it would be a good time to change the format of the docs. Due to API change I do not anticipate a lot of changes being back ported to the maintenance branch this release cycle (so the overhead of changing from reStructuedText to Markdown). If you already like Markdown you can skip the proposal and just look: - Compare example sphinx-build <https://geonetwork-opensource.org/manuals/4.0.x/en/overview/index.html> vs mkdocs <https://jodygarnett.github.io/core-geonetwork/4.2.5/> - Structure is unchanged so existing links to the docs do not break - Search actually works >From the proposal: The Journey is tough but the destination appears worth it. - Previously I learned convert content and not rewrite at the same time - This time I learned not to edit at all and made a script http://github.com/jodygarnett/translate - The script uses pandoc and then cleans up the mess for any sphinx-build directives that pandoc cannot support - A lot of the work went into reverse engineering doc and ref directives, and processing toctree directives that we would not wish to do by hand. These are all sphinx-build directives that require knowledge of documentation structure beyond a single file. - With such a powerful script it was often faster to fix problems in RST and re-convert (example for unexpected block quotes due to indenting) The destination: - mkdocs build is faster, and responsive when editing - the material theme is very good and well supported - mkdocs.yml requires a navigation tree of all pages (but there may be a plugin to glob *.md files) - Amazing: the search actually works - Disappointing: We give up some explicit features (guilabel, menuselection, file, download) and can make do with a clear writing guideline. It seems I may of been the only person appreciating these capabilities of sphinx-build - Great: Some of the advanced features we enjoy like literal-include are covered by markdown extensions - Bonus: version management for docs is much nicer Markdown is less expressive than sphinx-build, so we have to rely on a strong writing guideline to capture conventions that are no longer enforced by inline directives -- Jody Garnett
_______________________________________________ GeoTools-Devel mailing list GeoTools-Devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/geotools-devel
