[mapserver-dev] New MapScript API Docs

[Seth G]

Hi Tamas,

I have started the docs updates also - these will mainly consist of Sphinx directives to automatically generate the API docs from the codebase. The generation of API docs from the Python MapScript module will allow powerful linking between sections, and also highlight any undocumented methods and properties.

The comments for methods will be next to the relevant MapScript function declaration in the SWIG .i files. If new methods are added to MapScript the developer should add in a docstring in the format below:

* %feature("docstring") convertToString**
*
* "Output the CLASS as a Mapfile string"*
 %newobject convertToString;
 char* convertToString()
 {
 return msWriteClassToString(self);
 }

For object properties it was a choice between bloating header files, or keeping comment separate - I think the latter is cleaner, with each MapScript class having a .py file with comments that will match a property, and ideally linked to the relevant Mapfile section. E.g. 

*#: See :mapfile:`MAXSCALEDENOM <class.html#index-9>`**
*
*maxscaledenom = None*

The #index-9 is the only current way in Sphinx to link to an indexed document string (although hopefully this may change to something more robust in the future). 

I'm not currently sure of how best to document individual language extensions (typemaps etc.) - C# has some advanced features, as does Python. It is likely these extensions may need to be manually documented. 

I'll create a "developer docs" page detailing the above. 

So far I've only done classObj so it is going to take a couple of months to get the other objects completed. Hopefully maintenance after that will be limited. 

Seth

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


On Mon, Sep 16, 2019, at 11:23 AM, Tamas Szekeres wrote:
> Hi Seth,
> 
> This addition looks really cool. 
> Could you share some information about the developer's responsibilities to keep this documentation up to date?
> Is this intentional to add these files to the mapserver repo and not to the docs repo?
> 
> Tamas
> 
> 
> Seth G <sethg at geographika.co.uk> ezt írta (időpont: 2019. szept. 13., P, 18:07):
>> Hi all,
>> 
>>  I've made a WIP pull request at https://github.com/mapserver/mapserver/pull/5870 with a new approach to creating and maintaining the MapScript API docs. Once class down, many more to go! Hopefully I've got past most of the SWIG, Sphinx, autodoc, RST issues now and it is a case of checking and updating API docstrings. 
>> 
>>  Sample classObj page at http://www.geographika.net/mapserver-mapscript/mapscript/classes/class.html
>> 
>>  Questions, feedback and comments appreciated. 
>> 
>>  Seth
>> 
>>  --
>>  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/20190916/10c37324/attachment-0001.html>