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

[Peter Hutterer]

On Tue, Jul 24, 2018 at 09:27:51AM +0100, Daniel Stone wrote:
> 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.

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