[RFC libinput] dox: switch to sphinx for the user-visible documentation

[Daniel Stone]

Hey,

On Tue, 24 Jul 2018 at 06:43, Peter Hutterer <peter.hutterer at who-t.net> 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