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
------------------------------------------------------------------------------
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
