From bb5e87372cb8e440a5baf359923641b0f0a4da33 Mon Sep 17 00:00:00 2001 From: Markus Neteler Date: Wed, 18 Sep 2024 12:03:44 +0200 Subject: [PATCH 1/5] docs: move Programmer's manual creation to INSTALL.md - move Programmer's manual creation from `doc/development/README.md` to `INSTALL.md`. - update URLs and wording - list guides in `doc/development/README.md` --- INSTALL.md | 39 ++++++++++++++++++++++++++++--- doc/development/README.md | 49 +++++++-------------------------------- 2 files changed, 44 insertions(+), 44 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 41249a04143..60e47f01e97 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -321,9 +321,42 @@ developers mailing list. See ## (L) GRASS PROGRAMMER'S MANUAL -The Programmer's manual is generated with doxygen from the source code. -Please see the [README](doc/development/README.md) file and the files at: - +The Programmer's manual is +generated from the source code. This requires the installation of +`doxygen` () and optionally Graphviz `dot` +(). + +To locally generate the 'Programmer's Manual', run + +```sh +make htmldocs +``` + +To generate documentation as a single html file +(recommended for simple reading) + +```sh +make htmldocs-single +``` + +This process takes some time. The result will be found in +the file `lib/html/index.html` which itself refers to further +document repositories in + +```text +lib/vector/html/index.html +lib/db/html/index.html +lib/gis/html/index.html +``` + +The master file is: `./grasslib.dox` where all sub-documents have to +be linked to. + +To generate the 'Programmer's Manual' in PDF format, run + +```sh +make pdfdocs +``` ## (M) CONTRIBUTING CODE AND PATCHES diff --git a/doc/development/README.md b/doc/development/README.md index 9845f20649e..069c1c518d9 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -1,43 +1,10 @@ # Development and Maintenance Documentation -Here is development and maitanance documentation. The API documentation -is at appropriate places, but here is the information relevant to -contributing to GRASS GIS and its maintanance. - -## How to generate the 'Programmer's Manual' - -You can locally generate the [GRASS GIS Programmer's Manual](https://grass.osgeo.org/programming8/). - -This needs doxygen () and optionally -Graphviz dot (). - -To build the GRASS programmer's documentation, run - -```sh -make htmldocs -``` - -Or to generate documentation as a single html file -(recommended for simple reading) - -```sh -make htmldocs-single -``` - -This takes quite some time. The result is in `lib/html/index.html` -which refers to further document repositories in - -```text -lib/vector/html/index.html -lib/db/html/index.html -lib/gis/html/index.html -``` - -The master file is: `./grasslib.dox` where all sub-documents have to -be linked to. - -To generate the documents in PDF format, run - -```sh -make pdfdocs -``` +Find below the development and maintenance documentation. +The API documentation is available in the appropriate places, +but here is the information relevant to contributing to and +maintaining GRASS GIS. + +- [GRASS Programming Style Guide](./doc/development/style_guide.md) +- [Guide to contributing on GitHub](./doc/development/github_guide.md) +- [GRASS Programmer's manual](https://grass.osgeo.org/programming8/) From 77eab0005d2bb7003b581c978464e234eed8e35e Mon Sep 17 00:00:00 2001 From: Markus Neteler Date: Wed, 18 Sep 2024 15:12:36 +0200 Subject: [PATCH 2/5] remove stray control chars (visible in vim) --- doc/development/style_guide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/development/style_guide.md b/doc/development/style_guide.md index 8f1d5ab5245..3b065d9f838 100644 --- a/doc/development/style_guide.md +++ b/doc/development/style_guide.md @@ -122,7 +122,7 @@ sorted and separated by a newline. Use function names which fulfill the official [GNU naming convention](https://www.gnu.org/prep/standards/html_node/Names.html). Instead of -naming a function like: MyNewFunction() use snake case: my_new_function()`. +naming a function like: `MyNewFunction()` use snake case: `my_new_function()`. ### Using pre-commit @@ -192,7 +192,7 @@ There are three types of documentation: C API, Python API and tool documentation #### C API documentation We -[​use doxygen and document the functions](https://grass.osgeo.org/programming8/) +[use doxygen and document the functions](https://grass.osgeo.org/programming8/) directly in the source code. See `lib/gis/open.c` and `lib/gis/gislib.dox` for examples. @@ -947,7 +947,7 @@ gs.message(_("Running through {}").format(shellname)) ### Developing C tools Refer to the [online GRASS Programmer's -Manual](​https://grass.osgeo.org/programming8/) or generate it with `make +Manual](https://grass.osgeo.org/programming8/) or generate it with `make htmldocs` or `make pdfdocs`. #### Use GRASS library functions @@ -962,7 +962,7 @@ improves portability. - File seek: `G_fseek()`, `G_ftell()` - Printing: `G_asprintf()`, `G_vsaprintf()`, `G_vfaprintf()`, ... -Please refer to [the programmers manual](https://grass.osgeo.org/programming8/) +Please refer to the [programmers manual](https://grass.osgeo.org/programming8/) for the proper use (e.g., determining if any casts are needed for arguments or return values) of these library functions. They may perform a task slightly different from their corresponding C library function, and thus, their use may From 5fa20108ae687c1b76cdc3fe2d1032b30bd0144e Mon Sep 17 00:00:00 2001 From: Markus Neteler Date: Wed, 18 Sep 2024 15:18:08 +0200 Subject: [PATCH 3/5] add Python API; add subsections --- doc/development/README.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/doc/development/README.md b/doc/development/README.md index 069c1c518d9..bec7825f7d6 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -5,6 +5,15 @@ The API documentation is available in the appropriate places, but here is the information relevant to contributing to and maintaining GRASS GIS. -- [GRASS Programming Style Guide](./doc/development/style_guide.md) -- [Guide to contributing on GitHub](./doc/development/github_guide.md) +## Style guide and GitHub guide + +- [GRASS Programming Style Guide](style_guide.md) +- [Guide to contributing on GitHub](github_guide.md) + +## Python API + +- ["grass" Python package documentation](https://grass.osgeo.org/grass-devel/manuals/libpython/) + +## C API + - [GRASS Programmer's manual](https://grass.osgeo.org/programming8/) From 6ae9dc6470c2f3b26ddb94742f1805962d8165d8 Mon Sep 17 00:00:00 2001 From: Markus Neteler Date: Wed, 18 Sep 2024 15:20:40 +0200 Subject: [PATCH 4/5] simplify progman section --- INSTALL.md | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 60e47f01e97..7687266d7c8 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -326,6 +326,9 @@ generated from the source code. This requires the installation of `doxygen` () and optionally Graphviz `dot` (). +The main file is: `./grasslib.dox` where all sub-documents have +to be linked to. + To locally generate the 'Programmer's Manual', run ```sh @@ -340,17 +343,7 @@ make htmldocs-single ``` This process takes some time. The result will be found in -the file `lib/html/index.html` which itself refers to further -document repositories in - -```text -lib/vector/html/index.html -lib/db/html/index.html -lib/gis/html/index.html -``` - -The master file is: `./grasslib.dox` where all sub-documents have to -be linked to. +the file `lib/html/index.html`. To generate the 'Programmer's Manual' in PDF format, run From 8818fa51618a2ac22232ad79a868ee540b497185 Mon Sep 17 00:00:00 2001 From: Markus Neteler Date: Wed, 18 Sep 2024 15:22:41 +0200 Subject: [PATCH 5/5] subtitle rewording --- doc/development/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/development/README.md b/doc/development/README.md index bec7825f7d6..db5244a5a72 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -5,7 +5,7 @@ The API documentation is available in the appropriate places, but here is the information relevant to contributing to and maintaining GRASS GIS. -## Style guide and GitHub guide +## Style and GitHub guide - [GRASS Programming Style Guide](style_guide.md) - [Guide to contributing on GitHub](github_guide.md)