New MapScript API Docs

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

New MapScript API Docs

Seth G-2
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
[hidden email]
https://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: New MapScript API Docs

Howard Butler-3
Those look fantastic Seth. My dream of killing MapScript is never going to be realized.

On Fri, Sep 13, 2019 at 11:07 AM Seth G <[hidden email]> wrote:
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
[hidden email]
https://lists.osgeo.org/mailman/listinfo/mapserver-dev

_______________________________________________
mapserver-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: New MapScript API Docs

Andy Colson
On 9/14/19 8:57 AM, Howard Butler wrote:

> Those look fantastic Seth. My dream of killing MapScript is never going to be realized.
>
> On Fri, Sep 13, 2019 at 11:07 AM Seth G <[hidden email] <mailto:[hidden email]>> wrote:
>
>     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
>

Why do you want to kill MapScript?  I have poured everything into mapscript.

-Andy
_______________________________________________
mapserver-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: New MapScript API Docs

Howard Butler-3
Why do you want to kill MapScript?  I have poured everything into mapscript.

To kill MapScript is a running haha-but-serious joke I've had going for a long time with some of the MapServer developers. My case to do so is that MapScript has never been on par with mapfile and the mapfile definition for specifying objects and their relationships. Object lifetimes and their relationships were historically indefinite and sometimes inconsistent in MapScript. Additionally, any backwards compatibility considerations are often accommodated in mapfile, but were not addressed consistently in MapScript.

In my opinion, language-specific implementations were better off to use their own templating facilities and use the msLoad*FromString capability. This recognizes that mapfile is the definition of how MapServer renders images, it has validation of the object relationships, and the project does its best to protect mapfile compatibility as new versions are released.

Seth has done a ton of work on MapScript to fix all that and made MapScript better than it ever was. All of his work means it will probably never die :)

Howard

_______________________________________________
mapserver-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: New MapScript API Docs

Seth G-2
Howard - thanks for the encouragement for the docs. I guess if MapScript is to be kept alive it may as well have up-to-date docs!
I'm aware of the killing MapScript movement, and avoiding MapScript was the entire reason behind my writing the mappyfile library [1]. Sean Gillies who I believe was the last person to undertake significant MapScript changes finished up by writing the blog post "Stop Using MapScript"!

On the other hand MapScript has proved useful to many people and all with little to no maintenance for the last 15 years, and SWIG is fortunately still being maintained with a new v4 release a few months ago.

I've come to appreciate MapScript most in the following cases:

- allowing high quality cartographic output as part of Python workflows, mainly using the `draw` functions in MapScript
- as a second testing method for MapServer along with msautotest (via the Python test suite which now has > 300 tests)
- allowing reuse of MapServer functions directly in a scripting language without having to jump out into the command line (legend generation, scalebars, querying and reusing connection configurations etc.).

For Mapfile manipulation though I'd agree MapScript is far less useful than string templating and `fromstring` functions in the host language.

Just to note - we have Andy to thank for setting up Perl MapScript tests earlier this year - https://github.com/mapserver/mapserver/pull/5778
Andy - if you have any interest in setting up some more Perl typemaps or starting a Perl MapScript specific docs page let me know,

Seth


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


On Sun, Sep 15, 2019, at 4:22 PM, Howard Butler wrote:
Why do you want to kill MapScript?  I have poured everything into mapscript.

To kill MapScript is a running haha-but-serious joke I've had going for a long time with some of the MapServer developers. My case to do so is that MapScript has never been on par with mapfile and the mapfile definition for specifying objects and their relationships. Object lifetimes and their relationships were historically indefinite and sometimes inconsistent in MapScript. Additionally, any backwards compatibility considerations are often accommodated in mapfile, but were not addressed consistently in MapScript.

In my opinion, language-specific implementations were better off to use their own templating facilities and use the msLoad*FromString capability. This recognizes that mapfile is the definition of how MapServer renders images, it has validation of the object relationships, and the project does its best to protect mapfile compatibility as new versions are released.

Seth has done a ton of work on MapScript to fix all that and made MapScript better than it ever was. All of his work means it will probably never die :)

Howard
_______________________________________________
mapserver-dev mailing list
https://lists.osgeo.org/mailman/listinfo/mapserver-dev


_______________________________________________
mapserver-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: New MapScript API Docs

Tamas Szekeres
In reply to this post by Seth G-2
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 <[hidden email]> 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
[hidden email]
https://lists.osgeo.org/mailman/listinfo/mapserver-dev

_______________________________________________
mapserver-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: New MapScript API Docs

jmckenna
Administrator
In reply to this post by Seth G-2
It's actually the main reason why I moved the entire MS4W community on
Windows (who hugely rely on the MapScripts: PHP/Python/Charp) to use
SWIG MapScript - so we can more easily maintain one set of MapScript
documents.  I saw that as the best way to move forward, for the few
document volunteers to easily maintain MapScript docs (not a separate
PHP document).   There have been some growing pains for this, but I'm
very glad this happened.

-jeff



On 2019-09-15 4:20 PM, Seth G wrote:

> Howard - thanks for the encouragement for the docs. I guess if MapScript
> is to be kept alive it may as well have up-to-date docs!
> I'm aware of the killing MapScript movement, and avoiding MapScript was
> the entire reason behind my writing the mappyfile library [1]. Sean
> Gillies who I believe was the last person to undertake significant
> MapScript changes finished up by writing the blog post "Stop Using
> MapScript"!
>
> On the other hand MapScript has proved useful to many people and all
> with little to no maintenance for the last 15 years, and SWIG is
> fortunately still being maintained with a new v4 release a few months ago.
>
> I've come to appreciate MapScript most in the following cases:
>
> - allowing high quality cartographic output as part of Python workflows,
> mainly using the `draw` functions in MapScript
> - as a second testing method for MapServer along with msautotest (via
> the Python test suite which now has > 300 tests)
> - allowing reuse of MapServer functions directly in a scripting language
> without having to jump out into the command line (legend generation,
> scalebars, querying and reusing connection configurations etc.).
>
> For Mapfile manipulation though I'd agree MapScript is far less useful
> than string templating and `fromstring` functions in the host language.
>
> Just to note - we have Andy to thank for setting up Perl MapScript tests
> earlier this year - https://github.com/mapserver/mapserver/pull/5778
> Andy - if you have any interest in setting up some more Perl typemaps or
> starting a Perl MapScript specific docs page let me know,
>
> Seth
>
> [1] https://mappyfile.readthedocs.io/
> [2] https://sgillies.net/2006/11/29/stop-using-mapscript.html
>
> --
> web:http://geographika.co.uk
> twitter: @geographika
>
>
> On Sun, Sep 15, 2019, at 4:22 PM, Howard Butler wrote:
>>
>>     Why do you want to kill MapScript?  I have poured everything into
>>     mapscript.
>>
>>
>> To kill MapScript is a running haha-but-serious joke I've had going
>> for a long time with some of the MapServer developers. My case to do
>> so is that MapScript has never been on par with mapfile and the
>> mapfile definition for specifying objects and their relationships.
>> Object lifetimes and their relationships were historically indefinite
>> and sometimes inconsistent in MapScript. Additionally, any backwards
>> compatibility considerations are often accommodated in mapfile, but
>> were not addressed consistently in MapScript.
>>
>> In my opinion, language-specific implementations were better off to
>> use their own templating facilities and use the msLoad*FromString
>> capability. This recognizes that mapfile is the definition of how
>> MapServer renders images, it has validation of the object
>> relationships, and the project does its best to protect mapfile
>> compatibility as new versions are released.
>>
>> Seth has done a ton of work on MapScript to fix all that and made
>> MapScript better than it ever was. All of his work means it will
>> probably never die :)
>>
>> Howard
_______________________________________________
mapserver-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: New MapScript API Docs

Seth G-2
In reply to this post by Tamas Szekeres
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 <[hidden email]> 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.


Questions, feedback and comments appreciated.

Seth

--
twitter: @geographika
_______________________________________________
mapserver-dev mailing list


_______________________________________________
mapserver-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/mapserver-dev