QEMU-Devel Archive on lore.kernel.org
 help / color / Atom feed
* [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; 8+ 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	[flat|nested] 8+ 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; 8+ 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] 8+ 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; 8+ 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] 8+ 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
  2020-01-20 10:31     ` Peter Maydell
  0 siblings, 2 replies; 8+ 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] 8+ 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
  1 sibling, 1 reply; 8+ 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] 8+ 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; 8+ 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] 8+ 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; 8+ 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] 8+ 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
  1 sibling, 0 replies; 8+ 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] 8+ messages in thread

end of thread, back to index

Thread overview: 8+ 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

QEMU-Devel Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/qemu-devel/0 qemu-devel/git/0.git
	git clone --mirror https://lore.kernel.org/qemu-devel/1 qemu-devel/git/1.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 qemu-devel qemu-devel/ https://lore.kernel.org/qemu-devel \
		qemu-devel@nongnu.org
	public-inbox-index qemu-devel

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.nongnu.qemu-devel


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git