MS RFC 132: Update MapScript API Docs

[geographika]

This pull request implements RFC 132 - the (semi)-automatic generation of MapScript API documentation using the Python SWIG bindings.

To see the generated Sphinx output see MapScript API Index and MapScript Index Page.

Features

• Automatic stub generation based on the latest MapScript release. Keywords and functions.
• Any undocumented properties or functions has a TODO label added. The docs will always be up to date with the latest Python MapScript release
• Linking to Mapfile keywords to avoid duplication of docs (see Sphinx pull request)
• Linking to classes and functions available throughout docs, e.g. in HowTo and in the API docs themselves.
• Support for Python snippets from the Python test cases, ensuring examples continue to work with the latest codebase
• Set of Python scripts to update the list of available classes, constants, and enumerations, as well as class diagrams. These could also be set these to run automatically as part of the CI / docs build process
• Updates to the various MapScript HOWTO guides

Update Process

• On each MapServer version release Appveyor automatically publishes a source distribution of MapScript to PyPI
• The MapServer CI Travis script then downloads the distribution as part of the Sphinx documentation build. MapServer is not required to be installed - mocks are used so only Python .py files are required
• Various Sphinx extensions take care of creating pages for each of the MapScript classes

TODO

Note the Travis script is currently downloading mapscript from Test PyPI. A custom SWIG build was used to generate this as it allows for property annotations to be added automatically to the output. There is an open pull request in SWIG to add this (requiring some unit tests). Once this is added to SWIG mapscript can be downloaded from standard PyPI and added to requirements.txt

In conf.py nitpicky = True has been temporarily set to nitpicky = False. Many of the py:obj references were throwing errnoneous errors. These can be turned off using the following setting, but this is only available in the as-yet unrelease 4.1 version of Sphinx:

nitpick_ignore_regex = [('py:obj', 'mapscript.*')]](https://github.com/MapServer/MapServer/pull/ New in Sphinx version 4.1

Associated Pull Requests

Along with this documentation pull request, there are a number of updates to the MapServer sourcecode to add documentation strings along with the code:

• Update doxygen docstrings
• Mapscript legacy functions cleanup
• Document various MapServer structs
• Document webObj, styleObj and referenceMapObj
• Document outputFormatObj, projectionObj and map primitives
• Document labelCacheObj and associated objects (RFC 132)
• Add labelObj and layerObj comments to mapserver.h
• Document legendObj and lineObj
• Update mapObj comments and docstring fixes
• Document imageObj and hashTableObj
• Document the DBFInfo and shapefileObj with Doxygen comments
• Add property docstrings to classObj
• Add docstrings to all MapScript classes and methods
• SWIG Documentation for colorObj
• SWIG Documentation for clusterObj
• Add classObj property strings and update MapScript docstrings
• Add docstrings to SWIG objects
• Generated Mapscript API Documentation
• Document labelObj properties