MS RFC 132: Update MapScript API Docs

Date:

2020-05-29

Author:

Seth Girvin

Contact:

sethg@geographika.co.uk

Status:

Adopted

Last update:

2020-06-17

Version:

MapServer 8.0

Overview

This RFC proposes to add update the current MapScript API documentation at https://mapserver.org/mapscript/mapscript.html With PHP MapScript moving to SWIG correct API documentation has becoming increasingly important.

The current MapScript API documentation is currently updated manually. It contains many legacy methods, is missing newer methods, and missing documentation for some classes entirely.

This RFC proposes to use SWIG’s autodoc and docstring features along with Sphinx to update the MapScript API docs.

Links to sample output are below:

Features

  • Properties are liked to their relevant Mapfile documentation to avoid duplication and reduce maintenance (made possible due to this Sphinx pull request).

  • SWIG Python bindings can automatically have typehints generated, which in turn can be linked by Sphinx to automatically document function parameters, and link them to the relevant objects

  • Including comments with the code will improve the chances of mapscript documentation being updated

Documenting the Python bindings will also help IDE auto-completion and help when using the Python mapscript library.

Proposed Approach

  • Document all SWIG functions in the SWIG interface (.i) files

  • Document all properties in structs available to SWIG using doxygen-style comments

  • On each MapServer release a source distribution of the Python MapScript bindings will be pushed to PyPI - see https://github.com/MapServer/MapServer/pull/6011

  • mapscript will be added to the docs requirements.txt so the bindings are downloaded when building the docs automatically. Mocks will be used to MapServer is not required to import the C mapscript extensions.

  • The Sphinx extensions autodoc and autosummary will be used to generate the latest mapscript API information from the Python bindings

  • autosummary class templates will be used to add more prose, examples, and images where required

Possible Drawbacks

  • May be harder for non-devs to update code comments - however current and suggested approach both require Git knowledge

  • Docs approach differs from GDAL approach (see comments at https://lists.osgeo.org/pipermail/mapserver-dev/2020-May/016191.html) which requires no SWIG changes in the header files.

  • Header files will require editing to allow for additional comments. These will be doxygen style comments in the form /// comment and ///< trailing comment

Backward compatibility issues

  • Changes to the header files will break ABI compatibility so this update be included part of a release (minor or major).

  • When adding the docs there may be some struct fields made immutable or hidden from SWIG which should have been hidden already, for example see https://github.com/MapServer/MapServer/pull/5938

Documentation needs

None beyond this RFC.

Files

  • .i files in mapscripts/swiginc

  • .h files to document struct properties

  • the conf.py, requirements.txt files in the docs project

Ticket ID and reference

Voting history

+1 from MikeS, TomK, JeromeB, JukkaR, JeffM, DanielM, SteveL, EvenR, TamasS, SethG