<div dir="ltr"><br><div class="gmail_extra">Hi Luca,<br><br></div><div class="gmail_extra">that's great that you are working on that.<br></div><div class="gmail_extra"><br></div><div class="gmail_extra"><div class="gmail_quote">
On Tue, May 27, 2014 at 3:58 AM, Luca Delucchi <span dir="ltr"><<a href="mailto:lucadeluge@gmail.com" target="_blank">lucadeluge@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
I everybody,<br>
<br>
In the last days some improvements were done on pygrass documentation side [0].<br>
<br>
I would like to ask you:<br>
<br>
- what do you think about extend sphinx documentation to all python<br>
library of GRASS?<br></blockquote><div><br></div><div>Yes. Sphinx for the whole lib/python (grass.*). I'm not sure if additional separate for PyGRASS would make sense, probably not. Then it would be nice to have Sphinx for GUI (gui/wxpython).<br>
<br></div><div>Then I would disable all Python things (lib/python and gui/wxpython, the later for sure) in Doxygen because especially GUI creates a mess in Doxygen. It seems that Doxygen does not handle well all the things about Python modules, packages (especially if lib/python/* is changed into grass.*) and other Python features.<br>
<br></div><div>So than we would have tree documentations. Doxygen for C libraries, one Sphinx for Python libraries and one Sphinx for GUI.<br></div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
- could I replace doxigen instruction with sphinx instruction in<br>
pygrass docstrings? (for example replace @param with :param)<br>
<br></blockquote><div>Yes. And remove the exclamation marks at the beginning of docstrings ("""!...). (They are just using some undocumented Doxygen feature to enable processing of commands instead of using verbatim text for docstrings.)<br>
</div><div><br><br>On Tue, May 27, 2014 at 4:17 AM, Luca Delucchi <span dir="ltr"><<a href="mailto:lucadeluge@gmail.com" target="_blank">lucadeluge@gmail.com</a>></span> wrote:<br>On 27 May 2014 10:08, Martin Landa <<a href="mailto:landa.martin@gmail.com">landa.martin@gmail.com</a>> wrote:<br>
> ><br>
> > wouldn't be possible to use syntax which understands both sphinx and doxygen?<br>>
><br>> I don't think it is possible, but I don't know doxygen at all. Vaclav<br>> maybe know something more....<br>
<br></div><div>No, it is not possible. And I would probably be against even if it would be possible.<br><br></div><div>Explanations:<br></div><div><br>I don't say that the proposed solution is perfect but I was following this issue for more than a year and there is no better solution. The only official support of in Doxygen commands in Python are commands in comments (# ...). Docstrings are supposed to be copied as verbatim. The exclamation mark we are using is undocumented feature. reStructured text is almost standard for Python docstrings and is not supported in Doxygen and they does not seem to implement this support any time soon (see some other posts on this topic or my emails to doxygen mailing list).<br>
<br></div><div>It would be possible to have everything in Doxygen syntax and generate Sphinx from that using Breathe but this is not what we want. We want a tool which understands Python (that's Sphinx) and documentation style and syntax in code which works nicely (tools, editors) in Python world (that's reSturcturedText).<br>
<br></div><div>If the goal is to have everything in Doxygen-generated manual, I would say that we would need Sphinx anyway as a primary manual (that's what we are having this discussion) and Doxygen syntax would have to be generated from Python code with Sphinx/reStructuredText syntax in docstrings. This is possible in theory but we would have to create the conversion tool.<br>
</div><div><br>Feel free to ask additional question, I'll try to answer.<br><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
[0] <a href="http://grass.osgeo.org/grass71/manuals/pygrass/index.html" target="_blank">http://grass.osgeo.org/grass71/manuals/pygrass/index.html</a><br></blockquote><div><br></div><div>Nice, perhaps bit too conservative design but fits to GRASS manual nicely. I wish to have something similar for Doxygen but I'm afraid of maintenance issues.<br>
<br></div><div>Vaclav<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<span class=""><font color="#888888"><br>
--<br>
ciao<br>
Luca<br>
<br>
<a href="http://gis.cri.fmach.it/delucchi/" target="_blank">http://gis.cri.fmach.it/delucchi/</a><br>
<a href="http://www.lucadelu.org" target="_blank">www.lucadelu.org</a><br>
_______________________________________________<br>
grass-dev mailing list<br>
<a href="mailto:grass-dev@lists.osgeo.org">grass-dev@lists.osgeo.org</a><br>
<a href="http://lists.osgeo.org/mailman/listinfo/grass-dev" target="_blank">http://lists.osgeo.org/mailman/listinfo/grass-dev</a><br>
</font></span></blockquote></div><br></div></div>