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