Re: [RFC libinput] dox: switch to sphinx for the user-visible documentation
Hi, On Thu, 26 Jul 2018 at 02:53, Peter Hutterer wrote: > On Tue, Jul 24, 2018 at 03:42:50PM +1000, Peter Hutterer wrote: > > Sending this out as patch even though what really matters is the > > output. Which is... here, tadaaa! > > > > https://people.freedesktop.org/~whot/libinput-rtd/ > > fwiw, I've played around with it a bit and updated the URL above. It now has > a proper hierarchy, more doxygen tags are being parsed. > > There are still a few parsing issues that need to be fixed manually. And the > doc needs a general do-over to split it better into user docs vs developer > docs. And of course doxygen itself needs to be separated, generated, and > link to the sphinx docs. But otherwise this looks quite nice IMO. Oh, that is really nice. I like that it actually has a navigable hierarchy now. That was always my biggest issue with Doxygen. Given that the kernel also uses Sphinx for the DRM/KMS documentation in particular, it's probably good for us to be using it as well. If it counts for anything at all: Acked-by: Daniel Stone Cheers, Daniel PS: You might want to disable syntax highlighting on the MIT license; also 'generated by from git commit' at the very bottom. ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [RFC libinput] dox: switch to sphinx for the user-visible documentation
On Tue, Jul 24, 2018 at 03:42:50PM +1000, Peter Hutterer wrote: > Sending this out as patch even though what really matters is the > output. Which is... here, tadaaa! > > https://people.freedesktop.org/~whot/libinput-rtd/ fwiw, I've played around with it a bit and updated the URL above. It now has a proper hierarchy, more doxygen tags are being parsed. There are still a few parsing issues that need to be fixed manually. And the doc needs a general do-over to split it better into user docs vs developer docs. And of course doxygen itself needs to be separated, generated, and link to the sphinx docs. But otherwise this looks quite nice IMO. Cheers, Peter ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [RFC libinput] dox: switch to sphinx for the user-visible documentation
On Tue, Jul 24, 2018 at 09:27:51AM +0100, Daniel Stone wrote: > Hey, > > On Tue, 24 Jul 2018 at 06:43, Peter Hutterer wrote: > > Sending this out as patch even though what really matters is the > > output. Which is... here, tadaaa! > > > > https://people.freedesktop.org/~whot/libinput-rtd/ > > > > Basically the motivation here is to make the user-visible documentation less > > awful, especially because these days, 90% of the doc needs are by end users, > > not the developers. The API itself is just fine in doxygen, but for prose > > doxygen's "Related Pages" features is not perfect. > > > > So I'm wondering if using RTD-style documentation is a better option here. > > This patch is a more-or-less 1:1 conversion of the hand-written > > documentation to use sphinx with the RTD theme. For a good chuckle, look at > > the awk/sed script. (that script would go away anway after the one-time > > conversion to an .rst source format). > > Makes sense, and this does look really good, but ... did you remember > to run the script? The output at the URL above is full of @ref, @dot, > etc. The rest looks good though. :) I'm all for something like Sphinx > - not because I've ever used it or know any of its pros and cons, but > it seems like a more stable tooling which is also more widely used. oh right, the issues here are because this is the README.md which is the only file that doesn't filter through the sed/awk script. Other pages render correctly with the odd exceptions here and there. Doxygen allows @ref\nfoo but my sed script doesn't handle that case correctly. Cheers, Peter ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
Re: [RFC libinput] dox: switch to sphinx for the user-visible documentation
Hey, On Tue, 24 Jul 2018 at 06:43, Peter Hutterer wrote: > Sending this out as patch even though what really matters is the > output. Which is... here, tadaaa! > > https://people.freedesktop.org/~whot/libinput-rtd/ > > Basically the motivation here is to make the user-visible documentation less > awful, especially because these days, 90% of the doc needs are by end users, > not the developers. The API itself is just fine in doxygen, but for prose > doxygen's "Related Pages" features is not perfect. > > So I'm wondering if using RTD-style documentation is a better option here. > This patch is a more-or-less 1:1 conversion of the hand-written > documentation to use sphinx with the RTD theme. For a good chuckle, look at > the awk/sed script. (that script would go away anway after the one-time > conversion to an .rst source format). Makes sense, and this does look really good, but ... did you remember to run the script? The output at the URL above is full of @ref, @dot, etc. The rest looks good though. :) I'm all for something like Sphinx - not because I've ever used it or know any of its pros and cons, but it seems like a more stable tooling which is also more widely used. Cheers, Daniel ___ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
