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

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

[Alex Bennée]

..and extemporise a little about their state.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 documentation.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/documentation.md b/documentation.md
index f4ef9f4..55d5db6 100644
--- a/documentation.md
+++ b/documentation.md
@@ -3,9 +3,12 @@ title: QEMU documentation
 permalink: /documentation/
 ---
 
-The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be read online, courtesy of Stefan Weil.
-More documentation is found in the <a href="https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master">`docs`</a>
-directory of the QEMU git tree.
+The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be
+read online, courtesy of Stefan Weil. There is a partial set of
+[developer documentation](https://qemu.readthedocs.io/en/latest/)
+which is generated from the QEMU git tree. The process of converting
+the rest of the [`docs`](https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master)
+directory is ongoing.
 
 The [QEMU wiki](https://wiki.qemu.org) contains more
 [user documentation](https://wiki.qemu.org/Category:User_documentation) and
-- 
2.20.1

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

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 318 bytes --]

On Mon, Jan 13, 2020 at 10:35:50AM +0000, Alex Bennée wrote:
> ..and extemporise a little about their state.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  documentation.md | 9 ++++++---
>  1 file changed, 6 insertions(+), 3 deletions(-)

Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Thomas Huth]

On 13/01/2020 11.35, Alex Bennée wrote:
> ..and extemporise a little about their state.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  documentation.md | 9 ++++++---
>  1 file changed, 6 insertions(+), 3 deletions(-)
> 
> diff --git a/documentation.md b/documentation.md
> index f4ef9f4..55d5db6 100644
> --- a/documentation.md
> +++ b/documentation.md
> @@ -3,9 +3,12 @@ title: QEMU documentation
>  permalink: /documentation/
>  ---
>  
> -The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be read online, courtesy of Stefan Weil.
> -More documentation is found in the <a href="https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master">`docs`</a>
> -directory of the QEMU git tree.
> +The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be
> +read online, courtesy of Stefan Weil. There is a partial set of
> +[developer documentation](https://qemu.readthedocs.io/en/latest/)
> +which is generated from the QEMU git tree. The process of converting
> +the rest of the [`docs`](https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master)
> +directory is ongoing.

This has a conflict with Stefan's patch to point to our documentation on
www.qemu.org now instead:

 https://patchwork.kernel.org/patch/11234545/

... Stefan, looks like the index.html page is still not there yet,
although your other patch that includes index.html.in in the sources is
in the repository now? What's the status here?

 Thomas

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

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 2152 bytes --]

On Tue, Jan 14, 2020 at 12:11:34PM +0100, Thomas Huth wrote:
> On 13/01/2020 11.35, Alex Bennée wrote:
> > ..and extemporise a little about their state.
> > 
> > Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> > ---
> >  documentation.md | 9 ++++++---
> >  1 file changed, 6 insertions(+), 3 deletions(-)
> > 
> > diff --git a/documentation.md b/documentation.md
> > index f4ef9f4..55d5db6 100644
> > --- a/documentation.md
> > +++ b/documentation.md
> > @@ -3,9 +3,12 @@ title: QEMU documentation
> >  permalink: /documentation/
> >  ---
> >  
> > -The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be read online, courtesy of Stefan Weil.
> > -More documentation is found in the <a href="https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master">`docs`</a>
> > -directory of the QEMU git tree.
> > +The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be
> > +read online, courtesy of Stefan Weil. There is a partial set of
> > +[developer documentation](https://qemu.readthedocs.io/en/latest/)
> > +which is generated from the QEMU git tree. The process of converting
> > +the rest of the [`docs`](https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master)
> > +directory is ongoing.
> 
> This has a conflict with Stefan's patch to point to our documentation on
> www.qemu.org now instead:
> 
>  https://patchwork.kernel.org/patch/11234545/
> 
> ... Stefan, looks like the index.html page is still not there yet,
> although your other patch that includes index.html.in in the sources is
> in the repository now? What's the status here?

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.

It's good that we got ownership of the readthedocs.org account for QEMU.
I don't know if rtd will be capable of building QEMU's hodgepodge of
different documentation systems.  It supports Sphinx and Mkdocs but
that's not enough.

Can we redirect readthedocs to qemu.org?

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Alex Bennée]

Stefan Hajnoczi <stefanha@redhat.com> writes:

> On Tue, Jan 14, 2020 at 12:11:34PM +0100, Thomas Huth wrote:
>> On 13/01/2020 11.35, Alex Bennée wrote:
>> > ..and extemporise a little about their state.
>> > 
>> > Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> > ---
>> >  documentation.md | 9 ++++++---
>> >  1 file changed, 6 insertions(+), 3 deletions(-)
>> > 
>> > diff --git a/documentation.md b/documentation.md
>> > index f4ef9f4..55d5db6 100644
>> > --- a/documentation.md
>> > +++ b/documentation.md
>> > @@ -3,9 +3,12 @@ title: QEMU documentation
>> >  permalink: /documentation/
>> >  ---
>> >  
>> > -The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be read online, courtesy of Stefan Weil.
>> > -More documentation is found in the <a href="https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master">`docs`</a>
>> > -directory of the QEMU git tree.
>> > +The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be
>> > +read online, courtesy of Stefan Weil. There is a partial set of
>> > +[developer documentation](https://qemu.readthedocs.io/en/latest/)
>> > +which is generated from the QEMU git tree. The process of converting
>> > +the rest of the [`docs`](https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master)
>> > +directory is ongoing.
>> 
>> This has a conflict with Stefan's patch to point to our documentation on
>> www.qemu.org now instead:
>> 
>>  https://patchwork.kernel.org/patch/11234545/
>> 
>> ... Stefan, looks like the index.html page is still not there yet,
>> although your other patch that includes index.html.in in the sources is
>> in the repository now? What's the status here?
>
> 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.

And I think we want to continue hosting them on qemu.org. Is it possible
to theme them under the website branding? Stefan's version includes a
banner and background icon so it would be nice to at least fit in with
the reset of the site.

> It's good that we got ownership of the readthedocs.org account for QEMU.
> I don't know if rtd will be capable of building QEMU's hodgepodge of
> different documentation systems.  It supports Sphinx and Mkdocs but
> that's not enough.

Yeah at the moment we are just doing the sphinx side of things. AIUI the
long term plan is to convert stuff to .rst (at least for the developer
docs). 

> Can we redirect readthedocs to qemu.org?

Yeah rtd can label the canonical version of the docs as coming from your
own domain and link back (and importantly SEO juice it).

>
> Stefan


-- 
Alex Bennée

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

[Daniel P. Berrangé]

On Wed, Jan 15, 2020 at 11:56:04AM +0000, Alex Bennée wrote:
> 
> Stefan Hajnoczi <stefanha@redhat.com> writes:
> 
> > On Tue, Jan 14, 2020 at 12:11:34PM +0100, Thomas Huth wrote:
> >> On 13/01/2020 11.35, Alex Bennée wrote:
> >> > ..and extemporise a little about their state.
> >> > 
> >> > Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> >> > ---
> >> >  documentation.md | 9 ++++++---
> >> >  1 file changed, 6 insertions(+), 3 deletions(-)
> >> > 
> >> > diff --git a/documentation.md b/documentation.md
> >> > index f4ef9f4..55d5db6 100644
> >> > --- a/documentation.md
> >> > +++ b/documentation.md
> >> > @@ -3,9 +3,12 @@ title: QEMU documentation
> >> >  permalink: /documentation/
> >> >  ---
> >> >  
> >> > -The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be read online, courtesy of Stefan Weil.
> >> > -More documentation is found in the <a href="https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master">`docs`</a>
> >> > -directory of the QEMU git tree.
> >> > +The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be
> >> > +read online, courtesy of Stefan Weil. There is a partial set of
> >> > +[developer documentation](https://qemu.readthedocs.io/en/latest/)
> >> > +which is generated from the QEMU git tree. The process of converting
> >> > +the rest of the [`docs`](https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master)
> >> > +directory is ongoing.
> >> 
> >> This has a conflict with Stefan's patch to point to our documentation on
> >> www.qemu.org now instead:
> >> 
> >>  https://patchwork.kernel.org/patch/11234545/
> >> 
> >> ... Stefan, looks like the index.html page is still not there yet,
> >> although your other patch that includes index.html.in in the sources is
> >> in the repository now? What's the status here?
> >
> > 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.
> 
> And I think we want to continue hosting them on qemu.org. Is it possible
> to theme them under the website branding? Stefan's version includes a
> banner and background icon so it would be nice to at least fit in with
> the reset of the site.

I did a demo of this a while back:

  https://www.mail-archive.com/qemu-devel@nongnu.org/msg578110.html

Essentially you just need to strip the HTML header down to the
<body> content. Then add the jekyll header and run its site
generator which will add the new HTML header with theme.

In my patches above I committed the ref docs .html files to qemu-web.git
but this is not required. They just need to be placed in any directory
on the server where jekyll build process runs, so that we can access
them when building the static site content.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

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

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 3243 bytes --]

On Wed, Jan 15, 2020 at 12:01:34PM +0000, Daniel P. Berrangé wrote:
> On Wed, Jan 15, 2020 at 11:56:04AM +0000, Alex Bennée wrote:
> > 
> > Stefan Hajnoczi <stefanha@redhat.com> writes:
> > 
> > > On Tue, Jan 14, 2020 at 12:11:34PM +0100, Thomas Huth wrote:
> > >> On 13/01/2020 11.35, Alex Bennée wrote:
> > >> > ..and extemporise a little about their state.
> > >> > 
> > >> > Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> > >> > ---
> > >> >  documentation.md | 9 ++++++---
> > >> >  1 file changed, 6 insertions(+), 3 deletions(-)
> > >> > 
> > >> > diff --git a/documentation.md b/documentation.md
> > >> > index f4ef9f4..55d5db6 100644
> > >> > --- a/documentation.md
> > >> > +++ b/documentation.md
> > >> > @@ -3,9 +3,12 @@ title: QEMU documentation
> > >> >  permalink: /documentation/
> > >> >  ---
> > >> >  
> > >> > -The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be read online, courtesy of Stefan Weil.
> > >> > -More documentation is found in the <a href="https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master">`docs`</a>
> > >> > -directory of the QEMU git tree.
> > >> > +The [QEMU user manual](https://qemu.weilnetz.de/qemu-doc.html) can be
> > >> > +read online, courtesy of Stefan Weil. There is a partial set of
> > >> > +[developer documentation](https://qemu.readthedocs.io/en/latest/)
> > >> > +which is generated from the QEMU git tree. The process of converting
> > >> > +the rest of the [`docs`](https://git.qemu.org/?p=qemu.git;a=tree;f=docs;hb=master)
> > >> > +directory is ongoing.
> > >> 
> > >> This has a conflict with Stefan's patch to point to our documentation on
> > >> www.qemu.org now instead:
> > >> 
> > >>  https://patchwork.kernel.org/patch/11234545/
> > >> 
> > >> ... Stefan, looks like the index.html page is still not there yet,
> > >> although your other patch that includes index.html.in in the sources is
> > >> in the repository now? What's the status here?
> > >
> > > 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.
> > 
> > And I think we want to continue hosting them on qemu.org. Is it possible
> > to theme them under the website branding? Stefan's version includes a
> > banner and background icon so it would be nice to at least fit in with
> > the reset of the site.
> 
> I did a demo of this a while back:
> 
>   https://www.mail-archive.com/qemu-devel@nongnu.org/msg578110.html
> 
> Essentially you just need to strip the HTML header down to the
> <body> content. Then add the jekyll header and run its site
> generator which will add the new HTML header with theme.
> 
> In my patches above I committed the ref docs .html files to qemu-web.git
> but this is not required. They just need to be placed in any directory
> on the server where jekyll build process runs, so that we can access
> them when building the static site content.

I won't have time to play with this until after FOSDEM.

If anyone wants to send patches, please go ahead!

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Peter Maydell]

On Wed, 15 Jan 2020 at 11:11, Stefan Hajnoczi <stefanha@redhat.com> wrote:
> It's good that we got ownership of the readthedocs.org account for QEMU.
> I don't know if rtd will be capable of building QEMU's hodgepodge of
> different documentation systems.  It supports Sphinx and Mkdocs but
> that's not enough.

I think that as we continue to convert to rST format we should
end up somewhere where rtd can build everything. In particular
I realised last week that by using Sphinx extensions we don't
need to have our makefiles run necessarily to generate fragments
of document to include, the way we do for texinfo today, so
it should be possible to have the whole docset built just by
invoking Sphinx directly.

thanks
-- PMM

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

[Peter Maydell]

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 ?

PS: do you know which version of sphinx-build is being used
to build the docs for qemu.org ? We should check it's a
version that's python3-based, because I'm planning to tighten
up the configure check to reject python2 sphinxes (both for
consistency with our general Python version requirements, and
more specifically because the upcoming qapi-doc sphinx
extension I'm writing will import stuff from scripts/qapi
which needs Python 3).

thanks
-- PMM

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

[Thomas Huth]

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?

- 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?

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

 Thomas

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

[Peter Maydell]

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

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

[Thomas Huth]

On 03/02/2020 13.07, Peter Maydell wrote:
> 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.

Ok. Should we then just remove https://www.qemu.org/documentation/
completely and make the "Documentation" link in the "menu" point
directly to https://www.qemu.org/docs/master/ instead?
We could simply mention the Wiki in docs/index.html.in, too, I think?

 Thomas

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

[Peter Maydell]

On Mon, 3 Feb 2020 at 12:12, Thomas Huth <thuth@redhat.com> wrote:
> Ok. Should we then just remove https://www.qemu.org/documentation/
> completely and make the "Documentation" link in the "menu" point
> directly to https://www.qemu.org/docs/master/ instead?
> We could simply mention the Wiki in docs/index.html.in, too, I think?

I think I'd keep the current documentation/ page for now
(we probably don't want index.html.in to refer to the
developer documentation or the git tree).

thanks
-- PMM

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

[Peter Maydell]

On Mon, 3 Feb 2020 at 12:38, Peter Maydell <peter.maydell@linaro.org> wrote:
>
> On Mon, 3 Feb 2020 at 12:12, Thomas Huth <thuth@redhat.com> wrote:
> > Ok. Should we then just remove https://www.qemu.org/documentation/
> > completely and make the "Documentation" link in the "menu" point
> > directly to https://www.qemu.org/docs/master/ instead?
> > We could simply mention the Wiki in docs/index.html.in, too, I think?
>
> I think I'd keep the current documentation/ page for now
> (we probably don't want index.html.in to refer to the
> developer documentation or the git tree).

There's also a 'Manual' link in the footer thingy on every page
which currently goes to https://qemu.weilnetz.de/qemu-doc.html;
since we already have a 'Documentation' link to
https://www.qemu.org/documentation in the footer, I guess the
simplest thing there is to just delete the 'Manual' line.

thanks
-- PMM

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

[Thomas Huth]

On 03/02/2020 13.44, Peter Maydell wrote:
> On Mon, 3 Feb 2020 at 12:38, Peter Maydell <peter.maydell@linaro.org> wrote:
>>
>> On Mon, 3 Feb 2020 at 12:12, Thomas Huth <thuth@redhat.com> wrote:
>>> Ok. Should we then just remove https://www.qemu.org/documentation/
>>> completely and make the "Documentation" link in the "menu" point
>>> directly to https://www.qemu.org/docs/master/ instead?
>>> We could simply mention the Wiki in docs/index.html.in, too, I think?
>>
>> I think I'd keep the current documentation/ page for now
>> (we probably don't want index.html.in to refer to the
>> developer documentation or the git tree).
> 
> There's also a 'Manual' link in the footer thingy on every page
> which currently goes to https://qemu.weilnetz.de/qemu-doc.html;
> since we already have a 'Documentation' link to
> https://www.qemu.org/documentation in the footer, I guess the
> simplest thing there is to just delete the 'Manual' line.

Ok, I'll try to cook a patch...

 Thomas

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

[Thomas Huth]

On 03/02/2020 13.44, Peter Maydell wrote:
> On Mon, 3 Feb 2020 at 12:38, Peter Maydell <peter.maydell@linaro.org> wrote:
>>
>> On Mon, 3 Feb 2020 at 12:12, Thomas Huth <thuth@redhat.com> wrote:
>>> Ok. Should we then just remove https://www.qemu.org/documentation/
>>> completely and make the "Documentation" link in the "menu" point
>>> directly to https://www.qemu.org/docs/master/ instead?
>>> We could simply mention the Wiki in docs/index.html.in, too, I think?
>>
>> I think I'd keep the current documentation/ page for now
>> (we probably don't want index.html.in to refer to the
>> developer documentation or the git tree).
> 
> There's also a 'Manual' link in the footer thingy on every page
> which currently goes to https://qemu.weilnetz.de/qemu-doc.html;
> since we already have a 'Documentation' link to
> https://www.qemu.org/documentation in the footer, I guess the
> simplest thing there is to just delete the 'Manual' line.

I've now sent a patch ("[qemu-web PATCH] Update the documentation
links to point to our generated docs"), but I decided to keep the
"Manual" link there so that the footer does not look so empty (but
of course I've updated the link to the new location instead).

 Thomas

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

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 1213 bytes --]

On Mon, Feb 03, 2020 at 11:46:43AM +0000, 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 ?
> 
> PS: do you know which version of sphinx-build is being used
> to build the docs for qemu.org ? We should check it's a
> version that's python3-based, because I'm planning to tighten
> up the configure check to reject python2 sphinxes (both for
> consistency with our general Python version requirements, and
> more specifically because the upcoming qapi-doc sphinx
> extension I'm writing will import stuff from scripts/qapi
> which needs Python 3).

Yes, it's python3-sphinx:

  https://github.com/stefanha/qemu-docs/blob/master/Dockerfile#L14

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]