Hi Eduard, thank you for this. So it does seem like there are some significant downsides to using a single build.
You can see the combined result http://monomon.me/stuff/inkscape_doxygen. Toward the end there is a link to the subpage "Python Extension API", but check out how the rest of the docs are mixed up.
I'll also try separate documentation and see what it looks like. Currently trying to get the gitlab CI running locally in docker, and then I might integrate the doc build. Could we host the generated documentation on the website?
Is there a possibility to create "Chapters" or "Subprojects" (or anything similar) with doxygen?
My search shows that in Doxygen there are groups http://www.stack.nl/%7Edimitri/doxygen/manual/grouping.html which might do roughly what you meant. But I think ultimately the Class list and Namespaces list would still be mixed up (need to verify). We still have subpages, which link to commonly used classes, and are written manually.
Cheers, Mois
On 11/08/2017 03:48 PM, Eduard Braun wrote:
Hi Mois,
it's a bit hard to talk about this without seeing the actual result.
Why don't you link your local branch and/or create a "WIP" merge request so we can give some targeted feedback? If you even have a possibility to make the generated documentation available that would be great, too (then people can check it out directly without requiring a source checkout and doxygen and spare time to generate it).
Regarding mixing C++ and Python: That's exactly what I meant before and why I suggested to consider "separate" documents. It might make sense to generate them side-by-side if the different parts of the documentation are separated "well enough" but while searching in the C++ part I almost certainly do not require documentation on the Python extensions (and vice versa). For me (and probably most developers) and also technologically those parts are independent, so independent documentation would not hurt. I doubt C++ devs would be "irked" but if the information is not well separated it might add additional "noise" when working with it which does not exactly increase the usefulness of the documentation. Also I'm afraid extension developers might be "intimidated" if we throw the whole Inkscape code documentation their way if they only want information on a specific Python module (I assume we have many extension developers that are not actively involved in hacking Inkscape code itself). Is there a possibility to create "Chapters" or "Subprojects" (or anything similar) with doxygen? I.e. a single documentation that consists of multiple but independent parts? Obviously we could do that "manually" by simply linking to two independent doxygen documentations but I agree with you one complete self-contained documentation might be nice. Then again it's probably not much beyond "nice" and as said above it also wouldn't hurt if they are separate, so if there's no easy possibility to achieve this I'd probably just go with separate documents for the reasons outlined above...
Best Regards, Eduard
Am 08.11.2017 um 09:10 schrieb Mois:
Hey all,
this is a continuation of a thread regarding extensions documentation in general, but I am starting a new thread due to the slightly different focus.
I made changes that add the python sources to doxygen generation. This is already somewhat useful, because it is easy to see class methods with arguments at a glance.
Also made a doxygen 'subpage' for the python extensions, linking to some common classes in the extensions directory. (note: some input on this list is welcome)
Now, this is really nice, but has one downside - the Classes list and the Namespaces list contain python and c++ documentation all mixed up. Does anyone think it is a problem?
In my opinion, there are enough tools at hand to find the necessary documentation - e.g. seach, the "Inkscape Source Code Documentation" subpage, the files list (which is separated because the extensions and core code are in different directories).
I'd like to know whether any c++ devs would be irked by this.
Otherwise, I'll just submit a pull request.
It is also a possibility to create a new Doxyfile and output the extension docs in a separate directory. In a sense it 'feels right' for all documentation to be in one place, though.
Any thoughts?
Regards,
Mois
Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot
Inkscape-docs mailing list Inkscape-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-docs