Proposal mkdocs.md

User Manual refresh using Markdown and MkDocs

Date	2023-09-23	Contacts	Jody, Michel
Status	In progress	Release	GeoNetwork 4.4
Resources	Initial research completed by GeoCat, initial work completed by GeoCat and French speaking customers. GeoNetwork community process change on PR review to include docs. Ongoing translation required across GeoNetwork community	Ticket #	#7286
Source code	https://github.com/jodygarnett/iso19139.ca.HNAP/tree/mkddocs
Discussion	https://github.com/metadata101/iso19139.ca.HNAP/pull/348
Funding	GeoCat providing initial assessment on behalf of GeoNetwork Enterprise product

Overview

pandoc conversion of existing docs from sphinx-build rich-structured-text to mkdocs Markdown format.

• mkdocs: mkdocs example page

• sphinx: sphinx-build example page

This lowers barrier of entry as Markdown is much more popular then rich-structured text.

Technical Details:

• core-geonetwork codebase docs/ folder to directly manage user-manual alongside codebase.

  Pull-request reviews can now require update of docs alongside change of functionality / user-interface.

• Expand the Quickstart section into an End-user manual

• Selection of material for mkdocs theme offering clean appearance

  This combination offers several cool features: multi-lingual, tables, icons, ...

• Inclusion of translated files as entire documents (removing the use of Transfix for documentation)

  French: https://jodygarnett.github.io/iso19139.ca.HNAP/fr/search/records/

Bonus content:

• Updated writing guide to carefully write markdown that is compatible with both mkdocs and pandoc.

• A python translate script provided to automate the creation of new translation files using pandoc and deepl.

  # to create docs/devel/docs/docs.fr.md
  python3 -m translate french docs/devel/docs/docs.md

• pandoc can be used for initial conversion from sphinx-build, some pre-process is recommended.

• pandoc conversion of translated html files is also an option, if anyone wishes to preserve existing translations from Transfix.

Proposal Type:

• Type: refactor

• Module: documentation

• Vote Proposed: 2023-08-24

PSC members	vote
Jo Cook	+1
Jose Garcia	+1
Florent Gravin	+1
Simon Pigot
François-Xavier Prunayre	+1
Jeroen Ticheler	+1
Paul Van Genuchten

Participants

• All (Jody is not sure what this means)