* [qemu-web PATCH] documentation: update links to readthedocs @ 2020-01-13 10:35 Alex Bennée 2020-01-14 11:04 ` Stefan Hajnoczi 2020-01-14 11:11 ` Thomas Huth 0 siblings, 2 replies; 17+ messages in thread From: Alex Bennée @ 2020-01-13 10:35 UTC (permalink / raw) To: qemu-devel; +Cc: pbonzini, thuth, 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 ^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-01-13 10:35 [qemu-web PATCH] documentation: update links to readthedocs Alex Bennée @ 2020-01-14 11:04 ` Stefan Hajnoczi 2020-01-14 11:11 ` Thomas Huth 1 sibling, 0 replies; 17+ messages in thread From: Stefan Hajnoczi @ 2020-01-14 11:04 UTC (permalink / raw) To: Alex Bennée; +Cc: pbonzini, thuth, qemu-devel [-- 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 --] ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-01-13 10:35 [qemu-web PATCH] documentation: update links to readthedocs Alex Bennée 2020-01-14 11:04 ` Stefan Hajnoczi @ 2020-01-14 11:11 ` Thomas Huth 2020-01-15 11:10 ` Stefan Hajnoczi 1 sibling, 1 reply; 17+ messages in thread From: Thomas Huth @ 2020-01-14 11:11 UTC (permalink / raw) To: Alex Bennée, qemu-devel, Stefan Hajnoczi; +Cc: pbonzini 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-01-14 11:11 ` Thomas Huth @ 2020-01-15 11:10 ` Stefan Hajnoczi 2020-01-15 11:56 ` Alex Bennée ` (2 more replies) 0 siblings, 3 replies; 17+ messages in thread From: Stefan Hajnoczi @ 2020-01-15 11:10 UTC (permalink / raw) To: Thomas Huth; +Cc: pbonzini, Alex Bennée, qemu-devel [-- 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 --] ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-01-15 11:10 ` Stefan Hajnoczi @ 2020-01-15 11:56 ` Alex Bennée 2020-01-15 12:01 ` Daniel P. Berrangé 2020-01-20 10:31 ` Peter Maydell 2020-02-03 11:46 ` Peter Maydell 2 siblings, 1 reply; 17+ messages in thread From: Alex Bennée @ 2020-01-15 11:56 UTC (permalink / raw) To: Stefan Hajnoczi; +Cc: pbonzini, Thomas Huth, qemu-devel 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-01-15 11:56 ` Alex Bennée @ 2020-01-15 12:01 ` Daniel P. Berrangé 2020-01-20 10:16 ` Stefan Hajnoczi 0 siblings, 1 reply; 17+ messages in thread From: Daniel P. Berrangé @ 2020-01-15 12:01 UTC (permalink / raw) To: Alex Bennée; +Cc: pbonzini, Thomas Huth, qemu-devel, Stefan Hajnoczi 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 :| ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-01-15 12:01 ` Daniel P. Berrangé @ 2020-01-20 10:16 ` Stefan Hajnoczi 0 siblings, 0 replies; 17+ messages in thread From: Stefan Hajnoczi @ 2020-01-20 10:16 UTC (permalink / raw) To: Daniel P. Berrangé Cc: pbonzini, Thomas Huth, Alex Bennée, qemu-devel, 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 --] ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-01-15 11:10 ` Stefan Hajnoczi 2020-01-15 11:56 ` Alex Bennée @ 2020-01-20 10:31 ` Peter Maydell 2020-02-03 11:46 ` Peter Maydell 2 siblings, 0 replies; 17+ messages in thread From: Peter Maydell @ 2020-01-20 10:31 UTC (permalink / raw) To: Stefan Hajnoczi Cc: Paolo Bonzini, Thomas Huth, Alex Bennée, QEMU Developers 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-01-15 11:10 ` Stefan Hajnoczi 2020-01-15 11:56 ` Alex Bennée 2020-01-20 10:31 ` Peter Maydell @ 2020-02-03 11:46 ` Peter Maydell 2020-02-03 11:54 ` Thomas Huth 2020-02-05 10:28 ` Stefan Hajnoczi 2 siblings, 2 replies; 17+ messages in thread From: Peter Maydell @ 2020-02-03 11:46 UTC (permalink / raw) To: Stefan Hajnoczi Cc: Paolo Bonzini, Thomas Huth, Alex Bennée, QEMU Developers 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-02-03 11:46 ` Peter Maydell @ 2020-02-03 11:54 ` Thomas Huth 2020-02-03 12:07 ` Peter Maydell 2020-02-05 10:28 ` Stefan Hajnoczi 1 sibling, 1 reply; 17+ messages in thread From: Thomas Huth @ 2020-02-03 11:54 UTC (permalink / raw) To: Peter Maydell, Stefan Hajnoczi Cc: Paolo Bonzini, Alex Bennée, QEMU Developers 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-02-03 11:54 ` Thomas Huth @ 2020-02-03 12:07 ` Peter Maydell 2020-02-03 12:12 ` Thomas Huth 0 siblings, 1 reply; 17+ messages in thread From: Peter Maydell @ 2020-02-03 12:07 UTC (permalink / raw) To: Thomas Huth Cc: Paolo Bonzini, Alex Bennée, QEMU Developers, Stefan Hajnoczi 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-02-03 12:07 ` Peter Maydell @ 2020-02-03 12:12 ` Thomas Huth 2020-02-03 12:38 ` Peter Maydell 0 siblings, 1 reply; 17+ messages in thread From: Thomas Huth @ 2020-02-03 12:12 UTC (permalink / raw) To: Peter Maydell Cc: Paolo Bonzini, Alex Bennée, QEMU Developers, Stefan Hajnoczi 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-02-03 12:12 ` Thomas Huth @ 2020-02-03 12:38 ` Peter Maydell 2020-02-03 12:44 ` Peter Maydell 0 siblings, 1 reply; 17+ messages in thread From: Peter Maydell @ 2020-02-03 12:38 UTC (permalink / raw) To: Thomas Huth Cc: Paolo Bonzini, Alex Bennée, QEMU Developers, Stefan Hajnoczi 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-02-03 12:38 ` Peter Maydell @ 2020-02-03 12:44 ` Peter Maydell 2020-02-03 12:46 ` Thomas Huth 2020-02-03 13:21 ` Thomas Huth 0 siblings, 2 replies; 17+ messages in thread From: Peter Maydell @ 2020-02-03 12:44 UTC (permalink / raw) To: Thomas Huth Cc: Paolo Bonzini, Alex Bennée, QEMU Developers, Stefan Hajnoczi 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-02-03 12:44 ` Peter Maydell @ 2020-02-03 12:46 ` Thomas Huth 2020-02-03 13:21 ` Thomas Huth 1 sibling, 0 replies; 17+ messages in thread From: Thomas Huth @ 2020-02-03 12:46 UTC (permalink / raw) To: Peter Maydell Cc: Paolo Bonzini, Alex Bennée, QEMU Developers, Stefan Hajnoczi 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-02-03 12:44 ` Peter Maydell 2020-02-03 12:46 ` Thomas Huth @ 2020-02-03 13:21 ` Thomas Huth 1 sibling, 0 replies; 17+ messages in thread From: Thomas Huth @ 2020-02-03 13:21 UTC (permalink / raw) To: Peter Maydell Cc: Paolo Bonzini, Alex Bennée, QEMU Developers, Stefan Hajnoczi 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 ^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [qemu-web PATCH] documentation: update links to readthedocs 2020-02-03 11:46 ` Peter Maydell 2020-02-03 11:54 ` Thomas Huth @ 2020-02-05 10:28 ` Stefan Hajnoczi 1 sibling, 0 replies; 17+ messages in thread From: Stefan Hajnoczi @ 2020-02-05 10:28 UTC (permalink / raw) To: Peter Maydell Cc: Paolo Bonzini, Thomas Huth, Alex Bennée, QEMU Developers, 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 --] ^ permalink raw reply [flat|nested] 17+ messages in thread
end of thread, other threads:[~2020-02-05 10:29 UTC | newest] Thread overview: 17+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-01-13 10:35 [qemu-web PATCH] documentation: update links to readthedocs Alex Bennée 2020-01-14 11:04 ` Stefan Hajnoczi 2020-01-14 11:11 ` Thomas Huth 2020-01-15 11:10 ` Stefan Hajnoczi 2020-01-15 11:56 ` Alex Bennée 2020-01-15 12:01 ` Daniel P. Berrangé 2020-01-20 10:16 ` Stefan Hajnoczi 2020-01-20 10:31 ` Peter Maydell 2020-02-03 11:46 ` Peter Maydell 2020-02-03 11:54 ` Thomas Huth 2020-02-03 12:07 ` Peter Maydell 2020-02-03 12:12 ` Thomas Huth 2020-02-03 12:38 ` Peter Maydell 2020-02-03 12:44 ` Peter Maydell 2020-02-03 12:46 ` Thomas Huth 2020-02-03 13:21 ` Thomas Huth 2020-02-05 10:28 ` Stefan Hajnoczi
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).