Re: [docs] Possible changes to the project docs

["Robert P. J. Day" <rpjday@crashcourse.ca>]

On Wed, 15 Apr 2020, Richard Purdie wrote:

> Since Robert was talking about future docs wide changes, I wanted to
> put an idea out there. Its something a few of us have talked a
> little about. At this point it is an idea, not a decision and
> something we're thinking we need to explore and evaluate.
>
> Basically, the thought is whether to move from docbook to sphinx.
>
> Other projects like the kernel have switched and it could assist
> some of our website/publishing challenges. It might also be easier
> for people to contribute to and there are wider and more modern
> tools supporting that format.
>
> It'd be a big change, particularly if we consider we may need to
> convert previous releases of the docs as well as the current
> version. That said, if we were going to do this, the time could be
> now...

  ok, time to weigh in now that i have a minute ... i am totally on
board with a rewriting in sphinx, as that would not only make it
easier for others to contribute, but it's something that, given some
minimal direction, could be handed off to an intern of some kind or --
as i see already mentioned in subsequent replies -- fed through an
automatic translator (eg., pandoc).

  it would also be the right time to restructure some of the docs
(migration manual all on its own, etc, etc.).

  the only downside to the switch is that, as arcane as docbook and
xsl stylesheets can be at times, they do support pretty much infinite
and incredibly refined customization. however, i don't think the YP
docs really scream for that level of customization.

  i'm for it.

rday