[mapserver-dev] typedef struct versus struct in mapserver.h

[Even Rouault]

> The advantage of the SWIG docstrings is they can then be read from the
> Python source and then Sphinx can take over allowing internal doc links,
> inclusion of text, images, examples on a class by class basis.

Sure. But if SWIG can import Doxygen, that could perhaps serve the same purpose? (Using 
SWIG directly is ... well ... a particular experience)

While in brainstorming mode, one thing I wanted to mention is that we do use on GDAL and 
PROJ is Doxygen and import it in Sphinx, through the Breathe extension of Sphinx. But we do 
that just for documenting our C/C++ API.

Things like https://gdal.org/api/raster_c_api.html or 
https://proj.org/development/reference/cpp/crs.html are generated from that. 

Relevant entry points for GDAL:
- create Doxygen XML output:
	https://github.com/OSGeo/gdal/blob/master/gdal/doc/Makefile#L24
- declare Breathe extension in Sphinx configuration:
	https://github.com/OSGeo/gdal/blob/master/gdal/doc/source/conf.py#L423
- use part of the generated Doxygen doc:
	https://github.com/OSGeo/gdal/blob/master/gdal/doc/source/api/
raster_c_api.rst

Similar technics on PROJ.

That works pretty well. Occasionally we've hit some bugs on the Breathe/Sphinx side though.

But we haven't used that to create a documentation of the Python API

Even

-- 
Spatialys - Geospatial professional services
http://www.spatialys.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/mapserver-dev/attachments/20200525/dd3634db/attachment.html>