MkDocs

• Contact: Jody Garnett
• Tracker: https://osgeo-org.atlassian.net/browse/GEOT-1234
• TLDR: Change from sphinx-build to mkdocs for documentation generation
• Branch: https://github.com/geotools/geotools/tree/mkdocs

Description

Change from sphinx-build and reStructuredText to mkdocs and MarkDown.

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)
• Compare geonetwork: sphinx-build vs mkdocs
• Using automation it was even possible to migrate old versions that nobody wished to touch, making use of version selector possible even for very old content: geonetwork: 4.2, 3.12, 2.10

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

Work needed for GeoTools

GeoTools makes heavy use of literal-include in our documentation to include live code examples (that do not go out of date).

Making a decision on how to handle this, and updating the script to automate the conversion of literal-include is the key technical challenge for this activity.

About writing guidelines

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:

Markdown Convention.	sphinx-build inline directive
**strong**	gui label, menu selection
`monospace`	text input, item selection
*emphasis*	figure (caption)
***strong-emphasis***	application, command
monospace-strong	file

References:

• OGC documents
• https://squidfunk.github.io/mkdocs-material/
• https://www.mkdocs.org

Assigned to Release

If I can get this done for the 30.0 release (next week) it would be a good time to do so; much of the documentation needs updating and this would be a good visual change to go along with the code change.

GeoTools 30.0

Status

Choose one of:

• Under Discussion
• In Progress
• Completed
• Rejected,
• Deferred

Voting:

• Andrea Aime:
• Ian Turton:
• Jody Garnett:
• Nuno Oliveira:
• Simone Giannecchini:
• Torben Barsballe:

Tasks

This section is used to make sure your proposal is complete (did you remember documentation?) and has enough paid or volunteer time lined up to be a success. Use initials to indicate volunteer, or ⚠️ where volunteer is neededs. Proposals that lack resources to be successful are unlikely to be approved.

1. Run the script on geotools user docs
2. Update script to handle literal includes for code examples, using the mkdocs-include plugin
3. Update maven to call mkdocs rather than sphinx-build, packaging and so on remains unchanged
4. Backport to 30.x branch (in time for release)

Documentation Change

BEFORE:

##########
User Guide
##########

The GeoTools User Guide provides :doc:`tutorials introducing spatial concepts</tutorial/index>`,
:doc:`project background </welcome/index>`, and a reference section :doc:`covering each module </library/index>`, plugin
and :doc:`extension </extension/index>`.

.. sidebar:: Welcome to the User Guide
   
   Please report any issues with this documentation using the project issue tracker.
   
   * :doc:`Create an Issue </welcome/support>` .
   * `Known Documentation Issues <https://osgeo-org.atlassian.net/issues/?jql=project%20%3D%20GEOT%20AND%20component%20%3D%20docs>`_ (Issue Tracker)
   * `Jody Garnett <mailto: jody.garnett@gmail.com>`_ (Module Maintainer)
   
   For small typos and source code corrections email the module maintainer above.
   
   Version: |release|

AFTER:

# User Guide

The GeoTools User Guide provides [tutorials introducing spatial concepts](tutorial),
[project background](welcome), and a reference section [covering each module](library), plugin
and [extension](extension)`.

!!! info inline end "Welcome to the User Guide"
   
   Please report any issues with this documentation using the project issue tracker.
   
   * :[Create an Issue](welcome/support).
   * [Known Documentation Issues](https://osgeo-org.atlassian.net/issues/?jql=project%20%3D%20GEOT%20AND%20component%20%3D%20docs) (Issue Tracker)
   * [Jody Garnett](mailto:jody.garnett@gmail.com) (Module Maintainer)
   
   For small typos and source code corrections email the module maintainer above.
   
   Version: {{ version }}