[prev in list] [next in list] [prev in thread] [next in thread]
List: mapserver-dev
Subject: Re: [mapserver-dev] New MapScript API Docs
From: "Seth G" <sethg () geographika ! co ! uk>
Date: 2019-09-16 9:47:04
Message-ID: 7aeade6d-48be-4daa-a605-ad9996709fc2 () www ! fastmail ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
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@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@lists.osgeo.org
> > https://lists.osgeo.org/mailman/listinfo/mapserver-dev
[Attachment #5 (text/html)]
<!DOCTYPE html><html><head><title></title><style \
type="text/css">p.MsoNormal,p.MsoNoSpacing{margin:0}</style></head><body><div>Hi \
Tamas,<br></div><div><br></div><div>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.<br></div><div><br></div><div>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:<br></div><div><br></div><div><b> %feature("docstring") \
convertToString</b><b><br></b></div><div><b> "Output the CLASS as a \
Mapfile string"</b><br></div><div> %newobject \
convertToString;<br></div><div> char* \
convertToString()<br></div><div> \
{<br></div><div> return \
msWriteClassToString(self);<br></div><div> \
}<br></div><div><br></div><div>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. \
<br></div><div><br></div><div><b>#: See :mapfile:`MAXSCALEDENOM \
<class.html#index-9>`</b><b><br></b></div><div><b>maxscaledenom = \
None</b><br></div><div><br></div><div>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). <br></div><div><br></div><div>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. <br></div><div><br></div><div>I'll create a "developer docs" \
page detailing the above. <br></div><div><br></div><div>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. \
<br></div><div><br></div><div>Seth<br></div><div><br></div><div id="sig62266145"><div \
class="signature">--<br></div><div \
class="signature">web:http://geographika.co.uk<br></div><div \
class="signature">twitter: \
@geographika<br></div></div><div><br></div><div><br></div><div>On Mon, Sep 16, 2019, \
at 11:23 AM, Tamas Szekeres wrote:<br></div><blockquote type="cite" id="qt"><div \
dir="ltr"><div dir="ltr"><div>Hi Seth,<br></div><div><br></div><div>This addition \
looks really cool. <br></div><div>Could you share some information about the \
developer's responsibilities to keep this documentation up to date?<br></div><div>Is \
this intentional to add these files to the mapserver repo and not to the docs \
repo?<br></div><div><br></div><div>Tamas<br></div><div><br></div></div><div><br></div><div \
class="qt-gmail_quote"><div class="qt-gmail_attr" dir="ltr">Seth G <<a \
href="mailto:sethg@geographika.co.uk">sethg@geographika.co.uk</a>> ezt írta \
(időpont: 2019. szept. 13., P, 18:07):<br></div><blockquote \
style="margin-top:0px;margin-right:0px;margin-bottom:0px;margin-left:0.8ex;border-left-color:rgb(204, \
204, 204);border-left-style:solid;border-left-width:1px;padding-left:1ex;" \
class="qt-gmail_quote"><div>Hi all,<br></div><div> <br></div><div> I've made a WIP \
pull request at <a rel="noreferrer" \
href="https://github.com/mapserver/mapserver/pull/5870">https://github.com/mapserver/mapserver/pull/5870</a> \
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. <br></div><div> \
<br></div><div> Sample classObj page at <a rel="noreferrer" \
href="http://www.geographika.net/mapserver-mapscript/mapscript/classes/class.html">htt \
p://www.geographika.net/mapserver-mapscript/mapscript/classes/class.html</a><br></div><div> \
<br></div><div> Questions, feedback and comments appreciated. <br></div><div> \
<br></div><div> Seth<br></div><div> <br></div><div> --<br></div><div> web:<a \
rel="noreferrer" href="http://geographika.co.uk">http://geographika.co.uk</a><br></div><div> \
twitter: @geographika<br></div><div> \
_______________________________________________<br></div><div> mapserver-dev mailing \
list<br></div><div> <a \
href="mailto:mapserver-dev@lists.osgeo.org">mapserver-dev@lists.osgeo.org</a><br></div><div> \
<a rel="noreferrer" href="https://lists.osgeo.org/mailman/listinfo/mapserver-dev">http \
s://lists.osgeo.org/mailman/listinfo/mapserver-dev</a><br></div></blockquote></div></div></blockquote><div><br></div></body></html>
[Attachment #6 (text/plain)]
_______________________________________________
mapserver-dev mailing list
mapserver-dev@lists.osgeo.org
https://lists.osgeo.org/mailman/listinfo/mapserver-dev
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic