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/page.html
- 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
>
------------------------------------------------------------------------------
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
