docs: Generate manual from markdown using mkdocs (#3849)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Markus Neteler <[email protected]> Co-authored-by: Edouard Choinière <[email protected]> Co-authored-by: Markus Neteler <[email protected]> Co-authored-by: Vaclav Petras <[email protected]>
OSGeo · Nov 14, 2024 · 346c8a2 · 346c8a2
1 parent 91d652f
commit 346c8a2
Show file tree

Hide file tree

Showing 34 changed files with 2,089 additions and 1,096 deletions.
diff --git a/.flake8 b/.flake8
@@ -20,6 +20,7 @@ per-file-ignores =
     # E741 ambiguous variable name 'l'
     __init__.py: F403
     man/build_html.py: E501
+    man/build_md.py: E501
     doc/python/m.distance.py: E501
     gui/scripts/d.wms.py: E501
     gui/wxpython/image2target/g.gui.image2target.py: E501

diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md
@@ -35,6 +35,8 @@ for other platforms you may have to install some of them.
   GDAL: [https://gdal.org](https://gdal.org)
 - **Python >= 3.8** (for temporal framework, scripts, wxGUI, and ctypes interface)
   [https://www.python.org](https://www.python.org)
+- **MkDocs** with "Material" theme Python packages for the manual pages:
+  See `man/mkdocs/requirements.txt`.
 
 ## Optional packages
 

diff --git a/gui/scripts/Makefile b/gui/scripts/Makefile
@@ -1,7 +1,7 @@
 MODULE_TOPDIR = ../..
 
-include $(MODULE_TOPDIR)/include/Make/Rules.make
 include $(MODULE_TOPDIR)/include/Make/Vars.make
+include $(MODULE_TOPDIR)/include/Make/Rules.make
 include $(MODULE_TOPDIR)/include/Make/Python.make
 
 DSTDIR = $(GUIDIR)/scripts

diff --git a/include/Make/Grass.make b/include/Make/Grass.make
@@ -59,6 +59,7 @@ DOCSDIR         = $(ARCH_DISTDIR)/docs
 ETC             = $(ARCH_DISTDIR)/etc
 GUIDIR          = $(ARCH_DISTDIR)/gui
 HTMLDIR         = $(ARCH_DISTDIR)/docs/html
+MDDIR           = $(ARCH_DISTDIR)/docs/mkdocs
 SCRIPTDIR       = $(ARCH_DISTDIR)/scripts
 MSG_DIR         = $(ARCH_DISTDIR)/etc/msgs
 MO_DIR          = $(ARCH_DISTDIR)/locale

diff --git a/include/Make/GuiScript.make b/include/Make/GuiScript.make
@@ -10,6 +10,8 @@ include $(MODULE_TOPDIR)/include/Make/HtmlRules.make
 MODULES  := $(patsubst g.gui.%.py,%,$(wildcard g.gui.*.py))
 CMDHTML  := $(patsubst %,$(HTMLDIR)/g.gui.%.html,$(MODULES))
 GUIHTML  := $(patsubst %,$(HTMLDIR)/wxGUI.%.html,$(MODULES))
+CMDMAN := $(patsubst %,$(MDDIR)/source/g.gui.%.md,$(MODULES))
+GUIMAN  := $(patsubst %,$(MDDIR)/source/wxGUI.%.md,$(MODULES))
 ifdef MINGW
 SCRIPTEXT = .py
 BATFILES  := $(patsubst %,$(BIN)/g.gui.%.bat,$(MODULES))
@@ -19,26 +21,40 @@ BATFILES =
 endif
 PYFILES  := $(patsubst %,$(SCRIPTDIR)/g.gui.%$(SCRIPTEXT),$(MODULES))
 
-guiscript: $(IMGDST) $(PYFILES) $(BATFILES)
+guiscript: $(IMGDST) $(IMGDST_MD) $(PYFILES) $(BATFILES)
 # we cannot use cross-compiled g.parser for generating html files
 ifndef CROSS_COMPILING
 	$(MAKE) $(CMDHTML)
 	-rm -f g.gui.*.tmp.html
 	$(MAKE) $(GUIHTML)
+#	$(MAKE) $(CMDMAN)
+#	$(MAKE) $(GUIMAN)
 endif
 
 $(HTMLDIR)/g.gui.%.html: g.gui.%.html g.gui.%.tmp.html | $(HTMLDIR)
 	VERSION_NUMBER=$(GRASS_VERSION_NUMBER) VERSION_DATE=$(GRASS_VERSION_DATE) MODULE_TOPDIR=$(MODULE_TOPDIR) \
         $(PYTHON) $(GISBASE)/utils/mkhtml.py g.gui.$* $(GRASS_VERSION_DATE) > $@
 
+$(MDDIR)/source/g.gui.%.md: g.gui.%.md g.gui.%.tmp.md | $(MDDIR)
+	VERSION_NUMBER=$(GRASS_VERSION_NUMBER) VERSION_DATE=$(GRASS_VERSION_DATE) MODULE_TOPDIR=$(MODULE_TOPDIR) \
+        $(PYTHON) $(GISBASE)/utils/mkmarkdown.py g.gui.$* $(GRASS_VERSION_DATE) > $@
+
 $(HTMLDIR)/wxGUI.%.html: g.gui.%.html | $(HTMLDIR)
 	-rm -f g.gui.$*.tmp.html
 	VERSION_NUMBER=$(GRASS_VERSION_NUMBER) VERSION_DATE=$(GRASS_VERSION_DATE) MODULE_TOPDIR=$(MODULE_TOPDIR) \
         $(PYTHON) $(GISBASE)/utils/mkhtml.py g.gui.$* $(GRASS_VERSION_DATE) > $@
 
+$(MDDIR)/source/wxGUI.%.md: g.gui.%.md | $(MDDIR)
+	-rm -f g.gui.$*.tmp.md
+	VERSION_NUMBER=$(GRASS_VERSION_NUMBER) VERSION_DATE=$(GRASS_VERSION_DATE) MODULE_TOPDIR=$(MODULE_TOPDIR) \
+        $(PYTHON) $(GISBASE)/utils/mkmarkdown.py g.gui.$* $(GRASS_VERSION_DATE) > $@
+
 g.gui.%.tmp.html: $(SCRIPTDIR)/g.gui.%
 	$(call htmldesc,$<,$@)
 
+g.gui.%.tmp.md: $(SCRIPTDIR)/g.gui.%
+	$(call mddesc,$<,$@)
+
 $(SCRIPTDIR)/g.gui.%$(SCRIPTEXT): g.gui.%.py | $(SCRIPTDIR)
 	$(INSTALL) $< $@
 

diff --git a/include/Make/Html.make b/include/Make/Html.make
@@ -7,19 +7,26 @@ $(HTMLDIR)/%.html: %.html %.tmp.html $(HTMLSRC) $(IMGDST) | $(HTMLDIR)
 	VERSION_NUMBER=$(GRASS_VERSION_NUMBER) VERSION_DATE=$(GRASS_VERSION_DATE) MODULE_TOPDIR=$(MODULE_TOPDIR) \
         $(PYTHON) $(GISBASE)/utils/mkhtml.py $* > $@
 
+$(MDDIR)/source/%.md: %.md %.tmp.md $(HTMLSRC) $(IMGDST_MD) | $(MDDIR)
+	VERSION_NUMBER=$(GRASS_VERSION_NUMBER) VERSION_DATE=$(GRASS_VERSION_DATE) MODULE_TOPDIR=$(MODULE_TOPDIR) \
+        $(PYTHON) $(GISBASE)/utils/mkmarkdown.py $* > $@
+
 $(MANDIR)/%.$(MANSECT): $(HTMLDIR)/%.html
 	$(HTML2MAN) "$<" "$@"
 
 %.tmp.html: $(HTMLSRC)
 	if [ "$(HTMLSRC)" != "" ] ; then $(call htmldesc,$<,$@) ; fi
 
+%.tmp.md: $(HTMLSRC)
+	if [ "$(HTMLSRC)" != "" ] ; then $(call mddesc,$<,$@) ; fi
+
 ifdef CROSS_COMPILING
 
 html:
 
 else
 
-html: $(HTMLDIR)/$(PGM).html $(MANDIR)/$(PGM).$(MANSECT)
+html: $(HTMLDIR)/$(PGM).html $(MANDIR)/$(PGM).$(MANSECT) # $(MDDIR)/source/$(PGM).md
 
 endif
 

diff --git a/include/Make/HtmlRules.make b/include/Make/HtmlRules.make
@@ -3,13 +3,20 @@
 
 htmldesc = $(call run_grass,$(1) --html-description < /dev/null | grep -v '</body>\|</html>\|</div> <!-- end container -->' > $(2))
 
+mddesc = $(call run_grass,$(1) --md-description < /dev/null > $(2))
+
 IMGSRC := $(wildcard *.png) $(wildcard *.jpg) $(wildcard *.gif)
 IMGDST := $(patsubst %,$(HTMLDIR)/%,$(IMGSRC))
+IMGDST_MD := $(patsubst %,$(MDDIR)/source/%,$(IMGSRC))
 
 ifneq ($(strip $(IMGDST)),)
 .SECONDARY: $(IMGDST)
 endif
 
+ifneq ($(strip $(IMGDST_MD)),)
+.SECONDARY: $(IMGDST_MD)
+endif
+
 $(HTMLDIR)/%.png: %.png | $(HTMLDIR)
 	$(INSTALL_DATA) $< $@
 
@@ -18,3 +25,12 @@ $(HTMLDIR)/%.jpg: %.jpg | $(HTMLDIR)
 
 $(HTMLDIR)/%.gif: %.gif | $(HTMLDIR)
 	$(INSTALL_DATA) $< $@
+
+$(MDDIR)/source/%.png: %.png | $(MDDIR)
+	$(INSTALL_DATA) $< $@
+
+$(MDDIR)/source/%.jpg: %.jpg | $(MDDIR)
+	$(INSTALL_DATA) $< $@
+
+$(MDDIR)/source/%.gif: %.gif | $(MDDIR)
+	$(INSTALL_DATA) $< $@
diff --git a/include/Make/NoHtml.make b/include/Make/NoHtml.make
@@ -2,5 +2,8 @@
 $(HTMLDIR)/$(PGM).html:
 	@echo no HTML documentation available
 
+$(MDDIR)/source/$(PGM).md:
+	@echo no Markdown documentation available
+
 $(MANDIR)/$(PGM).$(MANSECT):
 	@echo no manual page available
diff --git a/include/Make/Rules.make b/include/Make/Rules.make
@@ -6,7 +6,7 @@ first: pre default
 ARCH_DIRS = $(ARCH_DISTDIR) $(ARCH_BINDIR) $(ARCH_INCDIR) $(ARCH_LIBDIR) \
 	$(BIN) $(ETC) \
 	$(DRIVERDIR) $(DBDRIVERDIR) $(FONTDIR) $(DOCSDIR) $(HTMLDIR) \
-	$(MANBASEDIR) $(MANDIR) $(UTILSDIR)
+	$(MDDIR) $(MDDIR)/source $(MANBASEDIR) $(MANDIR) $(UTILSDIR)
 
 pre: | $(ARCH_DIRS)
 

diff --git a/lib/gis/parser_rest_md.c b/lib/gis/parser_rest_md.c
@@ -4,7 +4,7 @@
    \brief GIS Library - Argument parsing functions (reStructuredText and
    Markdown output)
 
-   (C) 2012-2023 by the GRASS Development Team
+   (C) 2012-2024 by the GRASS Development Team
 
    This program is free software under the GNU General Public License
    (>=v2). Read the file COPYING that comes with GRASS for details.
@@ -20,6 +20,8 @@
 
 #include "parser_local_proto.h"
 
+#define MD_NEWLINE "  "
+
 static void usage_rest_md(bool rest);
 static void print_flag(const char *key, const char *label,
                        const char *description, bool rest);
@@ -41,7 +43,6 @@ void usage_rest_md(bool rest)
     struct Option *opt;
     struct Flag *flag;
     const char *type;
-    char *header = NULL;
     int new_prompt = 0;
 
     new_prompt = G__uses_new_gisprompt();
@@ -51,35 +52,17 @@ void usage_rest_md(bool rest)
     if (!st->pgm_name)
         st->pgm_name = "??";
 
-    /* main header */
-    G_asprintf(&header, "%s - GRASS GIS manual", st->pgm_name);
-    if (rest) {
-        size_t s;
-        fprintf(stdout, "%s\n", header);
-        for (s = 0; s < strlen(header); s++) {
-            fprintf(stdout, "=");
-        }
-        fprintf(stdout, "\n");
-    }
-    else {
-        fprintf(stdout, "# %s\n", header);
-    }
-    fprintf(stdout, "\n");
+    /* print metadata used by man/build*.py */
+    fprintf(stdout, "---\n");
+    fprintf(stdout, "name: %s\n", st->pgm_name);
+    fprintf(stdout, "description: %s\n", st->module_info.description);
+    fprintf(stdout, "keywords: ");
+    G__print_keywords(stdout, NULL, FALSE);
+    fprintf(stdout, "\n---\n\n");
 
-    /* GRASS GIS logo */
-    if (rest) {
-        fprintf(stdout, ".. image:: grass_logo.png\n");
-        fprintf(stdout, "   :align: center\n");
-        fprintf(stdout, "   :alt: GRASS logo\n");
-    }
-    else {
-        fprintf(stdout, "![GRASS logo](./grass_logo.png)\n");
-    }
-    /* horizontal line */
-    fprintf(stdout, "\n---");
-    if (rest)
-        fprintf(stdout, "-");
-    fprintf(stdout, "\n\n");
+    /* main header */
+    if (!rest)
+        fprintf(stdout, "# %s\n\n", st->pgm_name);
 
     /* header - GRASS module */
     if (!rest)
@@ -88,7 +71,7 @@ void usage_rest_md(bool rest)
     if (rest)
         fprintf(stdout, "----");
     fprintf(stdout, "\n");
-    fprintf(stdout, "**%s**", st->pgm_name);
+    fprintf(stdout, "***%s***", st->pgm_name);
 
     if (st->module_info.label || st->module_info.description)
         fprintf(stdout, " - ");
@@ -130,13 +113,13 @@ void usage_rest_md(bool rest)
     }
     fprintf(stdout, "**%s**", st->pgm_name);
     if (!rest)
-        fprintf(stdout, "\\");
+        fprintf(stdout, MD_NEWLINE);
     fprintf(stdout, "\n");
     if (rest)
         fprintf(stdout, "| ");
     fprintf(stdout, "**%s --help**", st->pgm_name);
     if (!rest)
-        fprintf(stdout, "\\");
+        fprintf(stdout, MD_NEWLINE);
     fprintf(stdout, "\n");
     if (rest)
         fprintf(stdout, "| ");
@@ -219,7 +202,7 @@ void usage_rest_md(bool rest)
         while (st->n_flags && flag != NULL) {
             print_flag(&flag->key, flag->label, flag->description, rest);
             if (!rest)
-                fprintf(stdout, "\\");
+                fprintf(stdout, MD_NEWLINE);
             fprintf(stdout, "\n");
             flag = flag->next_flag;
         }
@@ -228,21 +211,21 @@ void usage_rest_md(bool rest)
                        _("Allow output files to overwrite existing files"),
                        rest);
             if (!rest)
-                fprintf(stdout, "\\");
+                fprintf(stdout, MD_NEWLINE);
             fprintf(stdout, "\n");
         }
     }
     print_flag("help", NULL, _("Print usage summary"), rest);
     if (!rest)
-        fprintf(stdout, "\\");
+        fprintf(stdout, MD_NEWLINE);
     fprintf(stdout, "\n");
     print_flag("verbose", NULL, _("Verbose module output"), rest);
     if (!rest)
-        fprintf(stdout, "\\");
+        fprintf(stdout, MD_NEWLINE);
     fprintf(stdout, "\n");
     print_flag("quiet", NULL, _("Quiet module output"), rest);
     if (!rest)
-        fprintf(stdout, "\\");
+        fprintf(stdout, MD_NEWLINE);
     fprintf(stdout, "\n");
     print_flag("ui", NULL, _("Force launching GUI dialog"), rest);
     fprintf(stdout, "\n");
@@ -263,7 +246,7 @@ void usage_rest_md(bool rest)
             opt = opt->next_opt;
             if (opt != NULL) {
                 if (!rest)
-                    fprintf(stdout, "\\");
+                    fprintf(stdout, MD_NEWLINE);
             }
             fprintf(stdout, "\n");
         }
@@ -284,21 +267,23 @@ void print_flag(const char *key, const char *label, const char *description,
         fprintf(stdout, "-");
     fprintf(stdout, "-%s**", key);
     if (!rest)
-        fprintf(stdout, "\\");
+        fprintf(stdout, MD_NEWLINE);
     fprintf(stdout, "\n");
     if (label != NULL) {
         if (rest)
             fprintf(stdout, "| ");
         print_escaped(stdout, "\t", rest);
         print_escaped(stdout, label, rest);
         if (!rest)
-            fprintf(stdout, "\\");
+            fprintf(stdout, MD_NEWLINE);
         fprintf(stdout, "\n");
     }
-    if (rest)
-        fprintf(stdout, "| ");
-    print_escaped(stdout, "\t", rest);
-    print_escaped(stdout, description, rest);
+    if (description != NULL) {
+        if (rest)
+            fprintf(stdout, "| ");
+        print_escaped(stdout, "\t", rest);
+        print_escaped(stdout, description, rest);
+    }
 }
 
 void print_option(const struct Option *opt, bool rest, char *image_spec_rest)
@@ -341,7 +326,7 @@ void print_option(const struct Option *opt, bool rest, char *image_spec_rest)
         fprintf(stdout, " **[required]**");
     }
     if (!rest)
-        fprintf(stdout, "\\");
+        fprintf(stdout, MD_NEWLINE);
     fprintf(stdout, "\n");
     if (opt->label) {
         if (rest)
@@ -352,7 +337,7 @@ void print_option(const struct Option *opt, bool rest, char *image_spec_rest)
     if (opt->description) {
         if (opt->label) {
             if (!rest)
-                fprintf(stdout, "\\");
+                fprintf(stdout, MD_NEWLINE);
             fprintf(stdout, "\n");
         }
         if (rest)
@@ -363,7 +348,7 @@ void print_option(const struct Option *opt, bool rest, char *image_spec_rest)
 
     if (opt->options) {
         if (!rest)
-            fprintf(stdout, "\\");
+            fprintf(stdout, MD_NEWLINE);
         fprintf(stdout, "\n");
         if (rest)
             fprintf(stdout, "| ");
@@ -375,7 +360,7 @@ void print_option(const struct Option *opt, bool rest, char *image_spec_rest)
 
     if (opt->def) {
         if (!rest)
-            fprintf(stdout, "\\");
+            fprintf(stdout, MD_NEWLINE);
         fprintf(stdout, "\n");
         if (rest)
             fprintf(stdout, "| ");
@@ -394,7 +379,7 @@ void print_option(const struct Option *opt, bool rest, char *image_spec_rest)
         while (opt->opts[i]) {
             if (opt->descs[i]) {
                 if (!rest)
-                    fprintf(stdout, "\\");
+                    fprintf(stdout, MD_NEWLINE);
                 fprintf(stdout, "\n");
                 char *thumbnails = NULL;
                 if (opt->gisprompt) {

diff --git a/lib/init/Makefile b/lib/init/Makefile
@@ -47,8 +47,9 @@ ifneq ($(strip $(MINGW)),)
 endif
 
 HTMLFILES := $(wildcard *.html)
+MDFILES := $(wildcard *.md)
 
-default: $(FILES) $(patsubst %,$(HTMLDIR)/%,$(HTMLFILES))
+default: $(FILES) $(patsubst %,$(HTMLDIR)/%,$(HTMLFILES)) $(patsubst %,$(MDDIR)/source/%,$(MDFILES))
 
 ifneq ($(strip $(MINGW)),)
 $(ARCH_BINDIR)/$(START_UP): grass.sh