Re: [qemu-web PATCH] documentation: update links to readthedocs

[Peter Maydell <peter.maydell@linaro.org>]

On Mon, 3 Feb 2020 at 11:55, Thomas Huth <thuth@redhat.com> wrote:
>
> On 03/02/2020 12.46, Peter Maydell wrote:
> > On Wed, 15 Jan 2020 at 11:11, Stefan Hajnoczi <stefanha@redhat.com> wrote:
> >> The qemu.git/master docs are built nightly here (index.html is now
> >> visible!):
> >> https://www.qemu.org/docs/master/
> >>
> >> qemu.org's docs are more useful at the moment since they include the
> >> user documentation in addition to the developer documentation.
> >
> > Our top-level documentation page https://www.qemu.org/documentation/
> > still points to https://qemu.weilnetz.de/qemu-doc.html -- should
> > we update that now to link to https://www.qemu.org/docs/master/
> > instead ?
>
> Sure, but I'm still waiting for someone to suggest a final patch here.
>
> Open questions:
>
> - Do we also want to link to readthedocs as suggested by Alex, or is our
>   own docs on www.qemu.org enough?

I think if we're hosting our own docs we should just link to
our own docs (which include the not-yet-converted-to-rST
parts, which readthedocs doesn't); linking to two different
versions of the same thing is just going to confuse users.

> - Do we still want to link to weilnetz.de (as it was the case with
>   StefanH's original patch https://patchwork.kernel.org/patch/11234545/)
>   or should that link be removed?

We should remove it; it's been really helpful for the project
that Stefan Weil has provided built-documentation we can link
to for all these years, but now we finally have an "authoritative"
built version on qemu.org that's what we should link to.
Again, having multiple links to different versions of the
same thing would just confuse people. (The exception is that
if we ever decide to provide "version 5.0 docs", "version 5.1
docs", "current master docs" on qemu.org we can do that, because
that's an understandable-to-end-users easily-describable reason
for there being different docs links).

> - Do we only link to https://www.qemu.org/docs/master/ or shall we
>   link to the individual docs (qemu-doc, qemu-qmp-ref, ...) ?

Just link to master/ would be my advice. Otherwise when we
add a new top-level manual (eg the under-discussion tools/
manual) we'll need to update this web page as well.

thanks
-- PMM