[mapserver-dev] MS RFC 132: Update MapScript API Docs ready for review

[Seth G]

Hi all,

Any further comments/questions on MS RFC 132?

Even raised the question about the `nitpick` being set to False. This is due to the resolution of MapScript variable links, but these can be hidden in Sphinx 4.1 which I believe may be released soon (the mileston deadline was 2 weeks ago). Once we update to Sphinx 4.1 `nitpick` can be set back to True. 

The other major blocker is getting a pull request into SWIG so class property types are automatically documented.
https://github.com/swig/swig/pull/1951 - I'll look again at fixing the tests and trying to get this merged. 
In the meantime to update the docs requires manually building MapScript with a custom SWIG and pushing to test.pypi.org

The pull request in its current state does build the MapScript API docs automatically, and contains over 10 years of updates/corrections to the current MapScript docs so I'd like to merge this into main in the next couple of days if there are no objections.

Once merged and the main branch is made to be the current release (8.0) the docs will appear as at: https://geographika.github.io/MapServer-documentation/mapscript/mapscript-api/index.html

Seth

--
web:http://geographika.co.uk
twitter: @geographika


On Tue, May 25, 2021, at 12:11 AM, Steve Lime wrote:
> Woohoo! Congrats and thanks for taking on such a large chunk of work - two milestones in one day is pretty cool. --Steve
> 
> On Mon, May 24, 2021 at 8:38 AM Seth G <sethg at geographika.co.uk> wrote:
>> Hi all,
>> 
>> I'm pleased to announce that the MapScript documentation generation, described in RFC132 [1] is now added to a pull request [2] ready for review. 
>> 
>> Features include:
>> 
>> * 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
>> 
>> 
>> Seth
>> 
>> [1] https://mapserver.org/id/development/rfc/ms-rfc-132.html
>> [2] https://github.com/MapServer/MapServer-documentation/pull/544
>> 
>> --
>> web:http://geographika.co.uk
>> twitter: @geographika
>> _______________________________________________
>> mapserver-dev mailing list
>> mapserver-dev at lists.osgeo.org
>> https://lists.osgeo.org/mailman/listinfo/mapserver-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/mapserver-dev/attachments/20210626/7988cc81/attachment.html>