From 7b7c244ad9a5f9f1236f4b97d04e02de9ec0ae34 Mon Sep 17 00:00:00 2001 From: Martin Landa Date: Sun, 16 Jun 2024 19:15:14 +0200 Subject: [PATCH] build index file --- man/Makefile | 9 + man/build_index.py | 40 +++- man/build_md.py | 491 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 530 insertions(+), 10 deletions(-) create mode 100644 man/build_md.py diff --git a/man/Makefile b/man/Makefile index 59cc4e252ee..1ee62f875fa 100644 --- a/man/Makefile +++ b/man/Makefile @@ -34,6 +34,10 @@ IDXSRC = full_index index topics keywords graphical_index manual_gallery class_g INDICES := $(patsubst %,$(HTMLDIR)/%.html,$(IDXSRC)) +# TODO: rename to INDICES_MD +IDXSRC_MD = index +INDICES_MD := $(patsubst %,$(MDDIR)/source/%.md,$(IDXSRC_MD)) + ALL_HTML := $(wildcard $(HTMLDIR)/*.*.html) ifneq (@(type sphinx-build2 > /dev/null),) @@ -48,6 +52,7 @@ default: $(DSTFILES) $(MAKE) $(INDICES) $(call build,check) $(MAKE) manpages + $(MAKE) $(INDICES_MD) $(MAKE) mkdocs # This must be a separate target so that evaluation of $(MANPAGES) @@ -116,6 +121,10 @@ $(HTMLDIR)/index.html: build_index.py build_html.py $(call build,index) touch $@ +$(MDDIR)/source/index.md: build_index.py build_md.py + $(call build,index) + touch $@ + $(HTMLDIR)/keywords.html: $(ALL_HTML) $(call build_keywords) touch $@ diff --git a/man/build_index.py b/man/build_index.py index 5a01787afe3..b8eb3549d7a 100644 --- a/man/build_index.py +++ b/man/build_index.py @@ -9,19 +9,39 @@ import sys import os -from build_html import * - -os.chdir(html_dir) - -filename = "index.html" -f = open(filename + ".tmp", "w") +from build_html import ( + write_html_header, + write_html_cmd_overview, + write_html_footer, + replace_file, + html_dir, + grass_version, +) +from build_md import ( + write_md_header, + write_md_cmd_overview, + write_md_footer, + md_dir, +) year = None if len(sys.argv) > 1: year = sys.argv[1] -write_html_header(f, "GRASS GIS %s Reference Manual" % grass_version, True) -write_html_cmd_overview(f) -write_html_footer(f, "index.html", year) -f.close() + +# HTML - to be removed +filename = "index.html" +os.chdir(html_dir) +with open(filename + ".tmp", "w") as f: + write_html_header(f, "GRASS GIS %s Reference Manual" % grass_version, True) + write_html_cmd_overview(f) + write_html_footer(f, "index.html", year) +replace_file(filename) + +filename = "index.md" +os.chdir(md_dir) +with open(filename + ".tmp", "w") as f: + write_md_header(f, "GRASS GIS %s Reference Manual" % grass_version, True) + write_md_cmd_overview(f) + write_md_footer(f, "index.md", year) replace_file(filename) diff --git a/man/build_md.py b/man/build_md.py new file mode 100644 index 00000000000..a75de2be00c --- /dev/null +++ b/man/build_md.py @@ -0,0 +1,491 @@ +#!/usr/bin/env python3 + +# utilities for generating Markdown indices +# inspired by build_md.py +# (C) 2003-2024 Markus Neteler and the GRASS Development Team +# Authors: +# Markus Neteler +# Glynn Clements +# Luca Delucchi +# Martin Landa + +import os +import string +from datetime import datetime + +# TODO: better fix this in include/Make/Html.make, see bug RT #5361 + +# exclude following list of modules from help index: + +exclude_mods = [ + "i.find", + "r.watershed.ram", + "r.watershed.seg", + "v.topo.check", + "helptext.html", +] + +# these modules don't use G_parser() + +desc_override = { + "g.parser": "Provides automated parser, GUI, and help support for GRASS scipts.", + "r.li.daemon": "Support module for r.li landscape index calculations.", +} + +# File template pieces follow + +header2_tmpl = string.Template( + r""" + +![GRASS GIS logo](grass_logo.png) +___ + +## GRASS GIS ${grass_version} Reference Manual + +**Geographic Resources Analysis Support System<**, commonly +referred to as [GRASS GIS](https://grass.osgeo.org), is a +[Geographic Information System](https://en.wikipedia.org/wiki/Geographic_information_system) (GIS) used for geospatial data management and +analysis, image processing, graphics/maps production, spatial +modeling, and visualization. GRASS is currently used in academic and +commercial settings around the world, as well as by many governmental +agencies and environmental consulting companies. + +This reference manual details the use of modules distributed with +Geographic Resources Analysis Support System (GRASS), an open source +([GNU GPLed](https://www.gnu.org/licenses/gpl.html), image +processing and geographic information system (GIS). + +""" +) + +overview_tmpl = string.Template( + r""" + + + + + + + + + + + + + + + + + + + + + + + + +

 Quick Introduction

+ +

+

+

+

+

+

+

 Graphical User Interface

+ + + +

 Display

+ +

 General

+ +

 Addons

+ +

 Programmer's Manual

+ +

 Raster processing

+ +

 3D raster processing

+

 Image processing

+

 Vector processing

+

 Database

+ +

 Temporal processing

+ +

 Cartography

+ +

 Miscellaneous & Variables

+ +

 Python

+ +
+""" +) +# " + +footer_tmpl = string.Template( # TODO: https://trac.osgeo.org/grass/ticket/3987 + # r""" + #

wxGUI: Graphical user interface

+ # + # + # + #
wxGUI Graphical User Interface wxGUI Graphical User Interface
3D visualization suite wxGUI.nviz 3D visualization suite
+ #

+ # + #

Further pages

+ # + # + # + # + # + # + # + # + # + # + # + #
database intro database intro
imagery intro imagery intro
projection intro projection intro
raster3D intro raster3D intro
raster intro raster intro
temporal intro temporal intro
vector intro vector intro
SQL SQL
Variables Variables
+ # + #

+ #

+ r"""---- +[Main index](${index_url}) | +[Topics index](topics.html) | +[Keywords index](keywords.html) | +[Graphical index](graphical_index.html) | +[Full index](full_index.html) + +© 2003-${year} +[GRASS Development Team](https://grass.osgeo.org), +GRASS GIS ${grass_version} Reference Manual +""" +) +# " + +cmd2_tmpl = string.Template( + r""" +

${cmd_label} commands (${cmd}.*)

+ +""" +) +# " + +desc1_tmpl = string.Template( + r""" +""" +) +# " + +toc = r""" +
+

Table of contents

+ +
+""" +# " + +modclass_intro_tmpl = string.Template( + r"""Go to ${modclass} introduction | topics

+""" +) +# " + +modclass_tmpl = string.Template( + r"""Go back to help overview +

${modclass} commands:

+
${basename} ${desc}
+""" +) +# " + +desc2_tmpl = string.Template( + r""" +""" +) +# " + + +full_index_header = r""" +Go back to help overview +""" +# " + + +message_tmpl = string.Template( + r"""Generated HTML docs in ${md_dir}/index.html +---------------------------------------------------------------------- +Following modules are missing the 'modulename.html' file in src code: +""" +) +# " + +moduletopics_tmpl = string.Template( + r""" +
  • ${name}
    • +""" +) +# " + +headertopics_tmpl = r""" + + + +
    + +GRASS logo +
    +

    Topics

    +
    ${basename} ${desc}
    +""" +) +# " + +headerpso_tmpl = r""" + + + + + + + +
    + +GRASS logo +
    +

    Parser standard options

    +