[Bug] manual: multi-tools and multi-addons lack short descriptions

[neteler]

Describe the bug

All multi-tools (r.li, i.sentinel addon, etc.) have a "meta" manual page.

Traditionally, these contained the full HTML header/footer (example), since no parser-related compilation is involved and the HTML file was copied as-is into the target manual subdirectory.

For a short period of time (I could not identify when the change happened), the reduced manual page structure starting with "DESCRIPTION" and without footer is apparently also accepted, and the full manual pages are built.

GRASS GIS core

Core example r.li meta manual page:

• https://github.com/OSGeo/grass/blob/main/raster/r.li/r.li.html
• https://grass.osgeo.org/grass84/manuals/r.li.html

Yet the title is not turned into a description:

https://grass.osgeo.org/grass84/manuals/raster.html

• [...]
• r.li.edgedensity Calculates edge density index on a raster map, using a 4 neighbour algorithm
• r.li <== empty
• r.li.mpa Calculates mean pixel attribute index on a raster map
• r.li.mps Calculates mean patch size index on a raster map, using a 4 neighbour algorithm
• [...]

GRASS GIS addons:

A similar problem arises with addons:

https://grass.osgeo.org/grass84/manuals/addons/

• [...]
• i.ann.maskrcnn.detect: Detect features in images using a Mask R-CNN model
• i.ann.maskrcnn: GRASS GIS Reference Manual <== undefined
• i.ann.maskrcnn.train: Train your Mask R-CNN network
• [...]
• r.futures.gridvalidation: Module for validating land change simulation on a grid
• r.futures: GRASS GIS Reference Manual <== undefined
• r.futures.parallelpga: Simulates landuse change using FUTURES (r.futures.pga) on multiple CPUs in parallel.
• [...]

Only those meta manual pages which still contain full headers/footers are fine.

Expected behavior

The current manual magic needs to be fixed/expanded to carry over the title as short description.

[niweshsah]

Hello, I’m Niwesh Sah, a sophomore pursuing B.Tech in Computer Science from India. I’m new to open source and would like to contribute to this issue as my first task.

I have a question to better understand the problem:
Do I need to manually write the descriptions for the modules that currently show "undefined" (e.g., i.ann.maskrcnn), or are these descriptions already present elsewhere and not being sourced properly in the manual generation process?

If possible, I’d love to work on this issue. Please let me know if I can proceed.

[neteler]

Do I need to manually write the descriptions for the modules that currently show "undefined" (e.g., i.ann.maskrcnn), or are these descriptions already present elsewhere and not being sourced properly in the manual generation process?

They used to be defined when the full HTML headers where still present (which is undesired).
Perhaps @petrasovaa or @tmszi have insights here?

I guess new code additions are needed in https://github.com/OSGeo/grass/blob/main/man/build_html.py and related files.

[tmszi]

Do I need to manually write the descriptions for the modules that currently show "undefined" (e.g., i.ann.maskrcnn), or are these descriptions already present elsewhere and not being sourced properly in the manual generation process?

They used to be defined when the full HTML headers where still present (which is undesired). Perhaps @petrasovaa or @tmszi have insights here?

I guess new code additions are needed in https://github.com/OSGeo/grass/blob/main/man/build_html.py and related files.

This "description" is generated by ./utils/mkhtml.py file according meta comment(s) or without them inside man source HTML page:

1. If HTML source man page contains following HTML meta comments, e.g. g.parser module

<!-- meta page name: g.parser -->
<!-- meta page name description: Provides full parser support for GRASS scripts. -->

then you get in generated man HTML page: NAME section with g.parser - Provides full parser support for GRASS scripts. (PGM + DESC)

2. If HTML source man page contains following HTML meta comment, e.g. r.li module

<!-- meta page description: Landscape structure analysis package overview -->

then you get in generated man HTML page: Landscape structure analysis package overview title only

3. If HTML source man page does not contains any HTML meta comment, e.g. r.surf.area module ("common" module man page), then you get in generated man HTML page: NAME section r.surf.area - Prints estimation of surface area for raster map. (PGM + DEC)

grass/utils/mkhtml.py

Lines 354 to 370 in c0b45cf

	name = re.search(r"(<!-- meta page name:)(.*)(-->)", src_data, re.IGNORECASE)
	pgm_desc = "GRASS GIS Reference Manual"
	if name:
	pgm = name.group(2).strip().split("-", 1)[0].strip()
	name_desc = re.search(
	r"(<!-- meta page name description:)(.*)(-->)", src_data, re.IGNORECASE
	)
	if name_desc:
	pgm_desc = name_desc.group(2).strip()
	desc = re.search(r"(<!-- meta page description:)(.*)(-->)", src_data, re.IGNORECASE)
	if desc:
	pgm = desc.group(2).strip()
	header_tmpl = string.Template(header_base + header_nopgm)
	elif not pgm_desc:
	header_tmpl = string.Template(header_base + header_pgm)
	else:
	header_tmpl = string.Template(header_base + header_pgm_desc)

grass/utils/mkhtml.py

Lines 122 to 131 in c0b45cf

	header_nopgm = """<h2>${PGM}</h2>
	"""
	header_pgm = """<h2>NAME</h2>
	<em><b>${PGM}</b></em>
	"""
	header_pgm_desc = """<h2>NAME</h2>
	<em><b>${PGM}</b></em> - ${PGM_DESC}
	"""

[neteler]

Thanks so much for these insights, @tmszi ! Honestly, this way:

1. If HTML source man page contains following HTML meta comments, e.g. g.parser module

<!-- meta page name: g.parser -->
<!-- meta page name description: Provides full parser support for GRASS scripts. -->

was new to me :) I'd suggest to add your explanations to https://github.com/OSGeo/grass/blob/main/doc/development/style_guide.md#documentation

[niweshsah]

@tmszi Can you also refer to the Python file that generates the documentation for https://grass.osgeo.org/grass84/manuals/r.li.html? I believe that the ./utils/mkhtml.py script you mentioned is responsible for generating individual pages like https://grass.osgeo.org/grass84/manuals/r.li.edgedensity.html or similar files. Could you confirm if my understanding is correct?

[petrasovaa]

@tmszi Can you also refer to the Python file that generates the documentation for https://grass.osgeo.org/grass84/manuals/r.li.html? I believe that the ./utils/mkhtml.py script you mentioned is responsible for generating individual pages like https://grass.osgeo.org/grass84/manuals/r.li.edgedensity.html or similar files. Could you confirm if my understanding is correct?

See how it's addressed in addons:
OSGeo/grass-addons#1290

[tmszi]

@tmszi Can you also refer to the Python file that generates the documentation for https://grass.osgeo.org/grass84/manuals/r.li.html?

r.li.html man page source code .

Generated r.li.html man page file location is in my GNU/Linux OS Gentoo distribution under /usr/lib64/grass85/docs/html/ directory:

test@test-gnu-linux:/usr/lib64/grass85/docs/html$ ls -l r.li.*
-rw-r--r-- 1 root root  7261 Jan 26 21:13 r.li.cwed.html
-rw-r--r-- 1 root root  6235 Jan 26 21:13 r.li.daemon.html
-rw-r--r-- 1 root root  6977 Jan 26 21:13 r.li.dominance.html
-rw-r--r-- 1 root root  8030 Jan 26 21:13 r.li.edgedensity.html
-rw-r--r-- 1 root root 10804 Jan 26 21:13 r.li.html
-rw-r--r-- 1 root root  7269 Jan 26 21:13 r.li.mpa.html
-rw-r--r-- 1 root root  6943 Jan 26 21:13 r.li.mps.html
-rw-r--r-- 1 root root  6917 Jan 26 21:13 r.li.padcv.html
-rw-r--r-- 1 root root  6920 Jan 26 21:13 r.li.padrange.html
-rw-r--r-- 1 root root  6898 Jan 26 21:13 r.li.padsd.html
-rw-r--r-- 1 root root  7171 Jan 26 21:13 r.li.patchdensity.html
-rw-r--r-- 1 root root  6747 Jan 26 21:13 r.li.patchnum.html
-rw-r--r-- 1 root root  6875 Jan 26 21:13 r.li.pielou.html
-rw-r--r-- 1 root root  7181 Jan 26 21:13 r.li.renyi.html
-rw-r--r-- 1 root root  6791 Jan 26 21:13 r.li.richness.html
-rw-r--r-- 1 root root  6913 Jan 26 21:13 r.li.shannon.html
-rw-r--r-- 1 root root  6731 Jan 26 21:13 r.li.shape.html
-rw-r--r-- 1 root root  6988 Jan 26 21:13 r.li.simpson.html

Content part of generated r.li.html man page:

test@test-gnu-linux:/usr/lib64/grass85/docs/html$ cat r.li.html | head -n 32
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <title>Landscape structure analysis package overview - GRASS GIS Manual</title>
 <meta name="Author" content="GRASS Development Team">
 <meta name="description" content="Landscape structure analysis package overview: GRASS GIS Reference Manual">
 <link rel="stylesheet" href="grassdocs.css" type="text/css">
 <meta http-equiv="content-language" content="en-us">
 <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body bgcolor="white">
<div id="container">

<a href="index.html"><img src="grass_logo.png" alt="GRASS logo"></a>
<h2>Landscape structure analysis package overview</h2>
<div class="toc">
<h4 class="toc">Table of contents</h4>
<ul class="toc">
    <li class="toc"><a href="#description" class="toc">DESCRIPTION</a></li>
    <li class="toc"><a href="#notes" class="toc">NOTES</a></li>
    <li class="toc"><a href="#examples" class="toc">EXAMPLES</a></li>
    <li class="toc"><a href="#see-also" class="toc">SEE ALSO</a></li>
    <li class="toc"><a href="#adding-new-indices" class="toc">ADDING NEW INDICES</a></li>
    <li class="toc"><a href="#references" class="toc">REFERENCES</a></li>
    <li class="toc"><a href="#authors" class="toc">AUTHORS</a></li>
</ul>
</div>
<!-- meta page description: Landscape structure analysis package overview -->
<h2><a name="description">DESCRIPTION</a></h2>

The <em>r.li</em> suite is a toolset for multiscale analysis of

I believe that the ./utils/mkhtml.py script you mentioned is responsible for generating individual pages like https://grass.osgeo.org/grass84/manuals/r.li.edgedensity.html or similar files. Could you confirm if my understanding is correct?

In the case of example r.li.* (root directory) module, all *.html was parsed by ./utils/mkhtml.py script during GRASS GIS source code compilation (according Makefile directive) including r.li.html src man page.