RFC: xfwm: xfconf documentation

[andre at andreldm.com]

gtk-doc [1] it's just a document generator, you can check how other Xfce projects (Thunar for instance) use it and try to apply to xfwm4, it's a bit tricky to setup it with autotools, but once that is done you just need to configure with --enable-gtk-doc, make will generate the docs in /docs folder.

1 - https://gitlab.gnome.org/GNOME/gtk-doc

Cheers,
Andre Miranda

Oct 25, 2022, 13:44 by lkml at metux.net:

> On 25.10.22 12:49, andre at andreldm.com wrote:
>
>> Hi Enrico,
>> Perhaps you can write documentation comments in gtk-doc format and have them automatically published in https://developer.xfce.org/ <https://developer.xfce.org/>
>>
>
> Interesting idea, I'll have a look at it :)
>
> I've never used it before, so do you happen to have a pointer to some
> good quickstart guide ?
>
>
> --mtx
>
>>
>> Cheers,
>> Andre Miranda
>>
>> Oct 25, 2022, 11:04 by lkml at metux.net:
>>
>>  On 25.10.22 04:34, Kevin Bowen wrote:
>>
>>  Hello Kevin,
>>
>>  Our documentation for xfconf is maintained at
>>  https://docs.xfce.org/xfce/xfconf/start Currently, we are using
>>  docuwiki to publish our docs.
>>
>>
>>  There's a specific reason why I chose to do it in the source code
>>  instead somewhere external: these are things that depend on the current
>>  source version - eg. when new settings are introduced, the doc can be
>>  fixed by the same commit.
>>
>>  I'm a great fan of in-code documentation and extracting things
>>  automatically: you can always get the right docs for the exact code
>>  version you're currently looking at. And, of course, the docs go though
>>  the same review process like the code itself. documentation as code ;-)
>>
>>  With Wiki's this is hard and complicated achieve, while directly in
>>  git it's pretty trivial.
>>
>>  My plan was letting the CI build these docs and put 'em into some public
>>  place, where they can directly be referenced from Wiki, so we never have
>>  to touch these pieces manually anymore. For the major releases, we can
>>  have separate Wiki entry pages, that always point to the autogenerated
>>  docs of the corresponding version.
>>
>>  Note that right now we're talking about deeper technical docs for the
>>  professionals (those who need to touch xfconf directly, instead of
>>  going through the settings UI) - that's not an end user manual.
>>
>>  I've taken a brief look at your MR and it looks like there is
>>  definitely some info there that would be useful to add.
>>
>>
>>  Note that it's still an early draft - lots of entries are yet empty,
>>  I'll first have to check in the code, what these options are really
>>  doing.
>>
>>
>>  --mtx
>>
>>  --     ---
>>  Hinweis: unverschlüsselte E-Mails können leicht abgehört und manipuliert
>>  werden ! Für eine vertrauliche Kommunikation senden Sie bitte ihren
>>  GPG/PGP-Schlüssel zu.
>>  ---
>>  Enrico Weigelt, metux IT consult
>>  Free software and Linux embedded engineering
>>  info at metux.net -- +49-151-27565287
>>  _______________________________________________
>>  Xfce4-dev mailing list
>>  Xfce4-dev at xfce.org
>>  https://mail.xfce.org/mailman/listinfo/xfce4-dev
>>
>>
>>
>> _______________________________________________
>> Xfce4-dev mailing list
>> Xfce4-dev at xfce.org
>> https://mail.xfce.org/mailman/listinfo/xfce4-dev
>>
>
> -- 
> ---
> Hinweis: unverschlüsselte E-Mails können leicht abgehört und manipuliert
> werden ! Für eine vertrauliche Kommunikation senden Sie bitte ihren
> GPG/PGP-Schlüssel zu.
> ---
> Enrico Weigelt, metux IT consult
> Free software and Linux embedded engineering
> info at metux.net -- +49-151-27565287
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.xfce.org/pipermail/xfce4-dev/attachments/20221025/e895e13c/attachment-0001.html>