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
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
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
Am 09.11.2017 um 10:13 schrieb Mois:
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.
- Thanks for getting to work on this! Perhaps people will also enjoy documenting things more, when they know that their documentation will be easily accessible, and so more helpful. I like how it shows where things are being used, and how it also includes info on standards and external library documentation (never noticed before).
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?
- I think that would be possible. It would require something like this (I think - Martin will probably know better, and might be able to assist with the django parts):
- adding the pages here: https://gitlab.com/inkscape/inkscape-docs-export-website - possibly automating this?
- adding the CSS and js links into a (new?) template file here: https://gitlab.com/inkscape/inkscape-web/blob/master/docs/templates/docs/pag...
- adding the CSS and js files here: https://gitlab.com/inkscape/inkscape-web/tree/master/inkscape/static
- possibly edit this file, to split of footer and header: https://gitlab.com/inkscape/inkscape-web/blob/master/docs/views.py
- add links to the website, so people can know about it existing
Kind Regards, Maren
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
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
Alright, here is a second attempt at generating the extensions docs. http://monomon.me/stuff/inkscape-doxygen-extensions/
Now they are separate from the Inkscape core documentation. It does seem more useful this way - otherwise there's too much...
I added a couple of small subpages which should be expanded down the line. They should probably also link extensively to the wiki.
I still haven't tried running the gitlab ci locally after my first failed attempt. Been working with docker for a bit and I like it, but it frequently has issues.
Anyway, going to make a pull request for this part, and will integrate into ci later.
Cheers, Mois
Hi Mois,
looking good!
I forwarded you mail to inkscape-devel (maybe we can get some additional feedback) but I don't see any obvious issues with the MR.
Regards, Eduard
Am 14.11.2017 um 17:48 schrieb Mois:
Alright, here is a second attempt at generating the extensions docs. http://monomon.me/stuff/inkscape-doxygen-extensions/
Now they are separate from the Inkscape core documentation. It does seem more useful this way - otherwise there's too much...
I added a couple of small subpages which should be expanded down the line. They should probably also link extensively to the wiki.
I still haven't tried running the gitlab ci locally after my first failed attempt. Been working with docker for a bit and I like it, but it frequently has issues.
Anyway, going to make a pull request for this part, and will integrate into ci later.
Cheers, 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
Thank you Eduard for notifying the devel list, and taking a look at the new documentation! Note that I have not yet written any additional documentation, just wanted to have the ability to generate from it first.
I was unable to run the gitlab ci locally, so I pushed to a separate branch and the gitlab server's ci ran on it. https://gitlab.com/monomon/inkscape/-/jobs/40347524
As you can see, the doxygen build failed, because doxygen is not installed on the ci machines. This probably means we have to change the Dockerfile to include that (*if* we are to include it).
It sucks a little that gitlab are *deprecating* the exec command, which allows you to build locally. This is a really good way to verify you didn't miss anything obvious before pushing out.
Cheers, Mois
participants (3)
-
Eduard Braun -
Maren Hachmann -
Mois