[Qemu-devel] [PATCH 0/2] docs: build and install the 'specs' manual

[Qemu-devel] [PATCH 0/2] docs: build and install the 'specs' manual

[Peter Maydell]

(Sorry for the initial send where I sent only the cover
letter and forgot to tell git send-email to send the
patches as well...)

With the recent addition of the XIVE documentation, we
now have some actual .rST format documentation in
docs/specs, so we should start building and installing
this manual.

Patch 1 in this series fixes up some minor problems with
docs/specs/index.rst which we didn't notice because we
weren't building the manual. Patch 2 adds the makefile
and config runes to do the build and install.

NB: there's a trivial textual conflict in Makefile
with the 'convert qemu-ga' patch I sent earlier today;
this applies direct on top of master.

thanks
-- PMM


Peter Maydell (2):
  docs/specs/index.rst: Fix minor syntax issues
  docs: Build and install specs manual

 Makefile             |  7 ++++++-
 docs/specs/conf.py   | 16 ++++++++++++++++
 docs/specs/index.rst |  9 +++++----
 3 files changed, 27 insertions(+), 5 deletions(-)
 create mode 100644 docs/specs/conf.py

-- 
2.20.1

[Qemu-devel] [PATCH 1/2] docs/specs/index.rst: Fix minor syntax issues

[Peter Maydell]

The docs/specs/index.rst has a couple of minor issues which
we didn't notice because we weren't building the manual:
 * the ToC entry for the new PPC XIVE docs points to
   a nonexistent file
 * the initial comment needs to be marked by '..', not '.',
   or it will appear in the output
 * the title doesn't match the capitialization used by
   the existing interop or devel manuals, and uses
   'full-system emulation' rather than the 'system emulation'
   that the interop manual title uses

Fix these minor issues before we start trying to build the manual.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/specs/index.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index 2e927519c2e..40adb97c5eb 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -1,8 +1,8 @@
-. This is the top level page for the 'specs' manual
+.. This is the top level page for the 'specs' manual
 
 
-QEMU full-system emulation guest hardware specifications
-========================================================
+QEMU System Emulation Guest Hardware Specifications
+===================================================
 
 
 Contents:
@@ -10,4 +10,5 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
-   xive
+   ppc-xive
+   ppc-spapr-xive
-- 
2.20.1

[Qemu-devel] [PATCH 2/2] docs: Build and install specs manual

[Peter Maydell]

Now we have some rST format docs in the docs/specs/ manual, we should
actually build and install it.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 Makefile           |  7 ++++++-
 docs/specs/conf.py | 16 ++++++++++++++++
 2 files changed, 22 insertions(+), 1 deletion(-)
 create mode 100644 docs/specs/conf.py

diff --git a/Makefile b/Makefile
index 8e2fc6624c3..cfb18f15254 100644
--- a/Makefile
+++ b/Makefile
@@ -731,6 +731,7 @@ distclean: clean
 	rm -rf .doctrees
 	$(call clean-manual,devel)
 	$(call clean-manual,interop)
+	$(call clean-manual,specs)
 	for d in $(TARGET_DIRS); do \
 	rm -rf $$d || exit 1 ; \
         done
@@ -781,6 +782,7 @@ endef
 .PHONY: install-sphinxdocs
 install-sphinxdocs: sphinxdocs
 	$(call install-manual,interop)
+	$(call install-manual,specs)
 
 install-doc: $(DOCS) install-sphinxdocs
 	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
@@ -962,7 +964,7 @@ docs/version.texi: $(SRC_PATH)/VERSION config-host.mak
 # and handles "don't rebuild things unless necessary" itself.
 # The '.doctrees' files are cached information to speed this up.
 .PHONY: sphinxdocs
-sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index.html
+sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index.html $(MANUAL_BUILDDIR)/specs/index.html
 
 # Canned command to build a single manual
 build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -W -n -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
@@ -975,6 +977,9 @@ $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel)
 $(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
 	$(call build-manual,interop)
 
+$(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
+	$(call build-manual,specs)
+
 qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
 	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")
 
diff --git a/docs/specs/conf.py b/docs/specs/conf.py
new file mode 100644
index 00000000000..4d56f3ae13c
--- /dev/null
+++ b/docs/specs/conf.py
@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+#
+# QEMU documentation build configuration file for the 'specs' manual.
+#
+# This includes the top level conf file and then makes any necessary tweaks.
+import sys
+import os
+
+qemu_docdir = os.path.abspath("..")
+parent_config = os.path.join(qemu_docdir, "conf.py")
+exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
+
+# This slightly misuses the 'description', but is the best way to get
+# the manual title to appear in the sidebar.
+html_theme_options['description'] = \
+    u'System Emulation Guest Hardware Specifications'
-- 
2.20.1

Re: [Qemu-devel] [PATCH 1/2] docs/specs/index.rst: Fix minor syntax issues

[Cédric Le Goater]

On 10/06/2019 17:24, Peter Maydell wrote:
> The docs/specs/index.rst has a couple of minor issues which
> we didn't notice because we weren't building the manual:
>  * the ToC entry for the new PPC XIVE docs points to
>    a nonexistent file
>  * the initial comment needs to be marked by '..', not '.',
>    or it will appear in the output
>  * the title doesn't match the capitialization used by
>    the existing interop or devel manuals, and uses
>    'full-system emulation' rather than the 'system emulation'
>    that the interop manual title uses
> 
> Fix these minor issues before we start trying to build the manual.

I only tested the pdf generation of each file with rst2pdf :/
 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

Reviewed-by: Cédric Le Goater <clg@kaod.org>

Thanks,

C.

> ---
>  docs/specs/index.rst | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/docs/specs/index.rst b/docs/specs/index.rst
> index 2e927519c2e..40adb97c5eb 100644
> --- a/docs/specs/index.rst
> +++ b/docs/specs/index.rst
> @@ -1,8 +1,8 @@
> -. This is the top level page for the 'specs' manual
> +.. This is the top level page for the 'specs' manual
>  
>  
> -QEMU full-system emulation guest hardware specifications
> -========================================================
> +QEMU System Emulation Guest Hardware Specifications
> +===================================================
>  
>  
>  Contents:
> @@ -10,4 +10,5 @@ Contents:
>  .. toctree::
>     :maxdepth: 2
>  
> -   xive
> +   ppc-xive
> +   ppc-spapr-xive
> 

Re: [Qemu-devel] [PATCH 2/2] docs: Build and install specs manual

[Aleksandar Markovic]

On Jun 10, 2019 5:25 PM, "Peter Maydell" <peter.maydell@linaro.org> wrote:
>
> Now we have some rST format docs in the docs/specs/ manual, we should
> actually build and install it.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---

Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>

>  Makefile           |  7 ++++++-
>  docs/specs/conf.py | 16 ++++++++++++++++
>  2 files changed, 22 insertions(+), 1 deletion(-)
>  create mode 100644 docs/specs/conf.py
>
> diff --git a/Makefile b/Makefile
> index 8e2fc6624c3..cfb18f15254 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -731,6 +731,7 @@ distclean: clean
>         rm -rf .doctrees
>         $(call clean-manual,devel)
>         $(call clean-manual,interop)
> +       $(call clean-manual,specs)
>         for d in $(TARGET_DIRS); do \
>         rm -rf $$d || exit 1 ; \
>          done
> @@ -781,6 +782,7 @@ endef
>  .PHONY: install-sphinxdocs
>  install-sphinxdocs: sphinxdocs
>         $(call install-manual,interop)
> +       $(call install-manual,specs)
>
>  install-doc: $(DOCS) install-sphinxdocs
>         $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
> @@ -962,7 +964,7 @@ docs/version.texi: $(SRC_PATH)/VERSION config-host.mak
>  # and handles "don't rebuild things unless necessary" itself.
>  # The '.doctrees' files are cached information to speed this up.
>  .PHONY: sphinxdocs
> -sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html
$(MANUAL_BUILDDIR)/interop/index.html
> +sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html
$(MANUAL_BUILDDIR)/interop/index.html $(MANUAL_BUILDDIR)/specs/index.html
>
>  # Canned command to build a single manual
>  build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -W -n -b
html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1
$(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
> @@ -975,6 +977,9 @@ $(MANUAL_BUILDDIR)/devel/index.html: $(call
manual-deps,devel)
>  $(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
>         $(call build-manual,interop)
>
> +$(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
> +       $(call build-manual,specs)
> +
>  qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
>         $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< >
$@,"GEN","$@")
>
> diff --git a/docs/specs/conf.py b/docs/specs/conf.py
> new file mode 100644
> index 00000000000..4d56f3ae13c
> --- /dev/null
> +++ b/docs/specs/conf.py
> @@ -0,0 +1,16 @@
> +# -*- coding: utf-8 -*-
> +#
> +# QEMU documentation build configuration file for the 'specs' manual.
> +#
> +# This includes the top level conf file and then makes any necessary
tweaks.
> +import sys
> +import os
> +
> +qemu_docdir = os.path.abspath("..")
> +parent_config = os.path.join(qemu_docdir, "conf.py")
> +exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
> +
> +# This slightly misuses the 'description', but is the best way to get
> +# the manual title to appear in the sidebar.
> +html_theme_options['description'] = \
> +    u'System Emulation Guest Hardware Specifications'
> --
> 2.20.1
>
>

Re: [Qemu-devel] [PATCH 1/2] docs/specs/index.rst: Fix minor syntax issues

[Aleksandar Markovic]

On Jun 10, 2019 5:25 PM, "Peter Maydell" <peter.maydell@linaro.org> wrote:
>
> The docs/specs/index.rst has a couple of minor issues which
> we didn't notice because we weren't building the manual:
>  * the ToC entry for the new PPC XIVE docs points to
>    a nonexistent file
>  * the initial comment needs to be marked by '..', not '.',
>    or it will appear in the output
>  * the title doesn't match the capitialization used by
>    the existing interop or devel manuals, and uses
>    'full-system emulation' rather than the 'system emulation'
>    that the interop manual title uses
>
> Fix these minor issues before we start trying to build the manual.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---

Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>

>  docs/specs/index.rst | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
>
> diff --git a/docs/specs/index.rst b/docs/specs/index.rst
> index 2e927519c2e..40adb97c5eb 100644
> --- a/docs/specs/index.rst
> +++ b/docs/specs/index.rst
> @@ -1,8 +1,8 @@
> -. This is the top level page for the 'specs' manual
> +.. This is the top level page for the 'specs' manual
>
>
> -QEMU full-system emulation guest hardware specifications
> -========================================================
> +QEMU System Emulation Guest Hardware Specifications
> +===================================================
>
>
>  Contents:
> @@ -10,4 +10,5 @@ Contents:
>  .. toctree::
>     :maxdepth: 2
>
> -   xive
> +   ppc-xive
> +   ppc-spapr-xive
> --
> 2.20.1
>
>

Re: [Qemu-devel] [PATCH 1/2] docs/specs/index.rst: Fix minor syntax issues

[Peter Maydell]

On Mon, 10 Jun 2019 at 22:41, Aleksandar Markovic
<aleksandar.m.mail@gmail.com> wrote:
>
>
> On Jun 10, 2019 5:25 PM, "Peter Maydell" <peter.maydell@linaro.org> wrote:
> >
> > The docs/specs/index.rst has a couple of minor issues which
> > we didn't notice because we weren't building the manual:
> >  * the ToC entry for the new PPC XIVE docs points to
> >    a nonexistent file
> >  * the initial comment needs to be marked by '..', not '.',
> >    or it will appear in the output
> >  * the title doesn't match the capitialization used by
> >    the existing interop or devel manuals, and uses
> >    'full-system emulation' rather than the 'system emulation'
> >    that the interop manual title uses
> >
> > Fix these minor issues before we start trying to build the manual.
> >
> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> > ---
>
> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>

Hi Aleksandar; I'm just wondering what you were meaning
with this acked-by tag. Generally acked-by means  (to me,
and I think usually with qemu) "this patch touches an
area that I maintain, I haven't reviewed it but I'm OK with
it". But this series isn't mips-related, so maybe you
meant reviewed-by instead ?

(Acked-by is a bit of an odd tag because it's less
clear what it means than reviewed-by or signed-off-by,
so it's not very surprising if you've picked up a
different opinion on what it's for.)

thanks
-- PMM

Re: [Qemu-devel] [PATCH 1/2] docs/specs/index.rst: Fix minor syntax issues

[Aleksandar Markovic]

On Jun 11, 2019 11:51 AM, "Peter Maydell" <peter.maydell@linaro.org> wrote:
>
> On Mon, 10 Jun 2019 at 22:41, Aleksandar Markovic
> <aleksandar.m.mail@gmail.com> wrote:
> >
> >
> > On Jun 10, 2019 5:25 PM, "Peter Maydell" <peter.maydell@linaro.org>
wrote:
> > >
> > > The docs/specs/index.rst has a couple of minor issues which
> > > we didn't notice because we weren't building the manual:
> > >  * the ToC entry for the new PPC XIVE docs points to
> > >    a nonexistent file
> > >  * the initial comment needs to be marked by '..', not '.',
> > >    or it will appear in the output
> > >  * the title doesn't match the capitialization used by
> > >    the existing interop or devel manuals, and uses
> > >    'full-system emulation' rather than the 'system emulation'
> > >    that the interop manual title uses
> > >
> > > Fix these minor issues before we start trying to build the manual.
> > >
> > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> > > ---
> >
> > Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
>
> Hi Aleksandar; I'm just wondering what you were meaning
> with this acked-by tag. Generally acked-by means  (to me,
> and I think usually with qemu) "this patch touches an
> area that I maintain, I haven't reviewed it but I'm OK with
> it". But this series isn't mips-related, so maybe you
> meant reviewed-by instead ?
>
> (Acked-by is a bit of an odd tag because it's less
> clear what it means than reviewed-by or signed-off-by,
> so it's not very surprising if you've picked up a
> different opinion on what it's for.)
>

Hello, Peter.

My intented meaning (of my Acked-by) is:

“I agree that this patch is valuable in general, I took a look at the code
changes and they look good to me implementation-wise, but I am not a
reviewer nor an expert in rst and related areas, so I am not comfortable
“reviewing-it-by” - however as a potential user/writer of rst files, I want
to acknowledge the significance and the rightness of the patch by
“acking-it-by”.”

I am not sure how it fits in other definitions, but I am comfortable with
your changing my “Acked-by” to “Reviewed-by”, leaving it as is, or changing
it to nothing- whatever you deem being suitable.

The same applies to the other patch of this series, of course.

Yours,
Aleksandar

> thanks
> -- PMM

Re: [Qemu-devel] [PATCH 1/2] docs/specs/index.rst: Fix minor syntax issues

[Aleksandar Markovic]

On Jun 11, 2019 4:18 PM, "Aleksandar Markovic" <aleksandar.m.mail@gmail.com>
wrote:
>
>
> On Jun 11, 2019 11:51 AM, "Peter Maydell" <peter.maydell@linaro.org>
wrote:
> >
> > On Mon, 10 Jun 2019 at 22:41, Aleksandar Markovic
> > <aleksandar.m.mail@gmail.com> wrote:
> > >
> > >
> > > On Jun 10, 2019 5:25 PM, "Peter Maydell" <peter.maydell@linaro.org>
wrote:
> > > >
> > > > The docs/specs/index.rst has a couple of minor issues which
> > > > we didn't notice because we weren't building the manual:
> > > >  * the ToC entry for the new PPC XIVE docs points to
> > > >    a nonexistent file
> > > >  * the initial comment needs to be marked by '..', not '.',
> > > >    or it will appear in the output
> > > >  * the title doesn't match the capitialization used by
> > > >    the existing interop or devel manuals, and uses
> > > >    'full-system emulation' rather than the 'system emulation'
> > > >    that the interop manual title uses
> > > >
> > > > Fix these minor issues before we start trying to build the manual.
> > > >
> > > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> > > > ---
> > >
> > > Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com>
> >
> > Hi Aleksandar; I'm just wondering what you were meaning
> > with this acked-by tag. Generally acked-by means  (to me,
> > and I think usually with qemu) "this patch touches an
> > area that I maintain, I haven't reviewed it but I'm OK with
> > it". But this series isn't mips-related, so maybe you
> > meant reviewed-by instead ?
> >
> > (Acked-by is a bit of an odd tag because it's less
> > clear what it means than reviewed-by or signed-off-by,
> > so it's not very surprising if you've picked up a
> > different opinion on what it's for.)
> >
>
> Hello, Peter.
>
> My intented meaning (of my Acked-by) is:
>
> “I agree that this patch is valuable in general, I took a look at the
code changes and they look good to me implementation-wise, but I am not a
reviewer nor an expert in rst and related areas, so I am not comfortable
“reviewing-it-by” - however as a potential user/writer of rst files, I want
to acknowledge the significance and the rightness of the patch by
“acking-it-by”.”
>
> I am not sure how it fits in other definitions, but I am comfortable with
your changing my “Acked-by” to “Reviewed-by”, leaving it as is, or changing
it to nothing- whatever you deem being suitable.
>
> The same applies to the other patch of this series, of course.
>
> Yours,
> Aleksandar
>
> > thanks
> > -- PMM

Peter, hi again.

While the content of this patch seems definitely unrelated to mips, we in
mips are very interested in QEMU documention framework extended and
improved, since we plan (in a mid-term) a major overhaul of both external
and internal mips-related QEMU documentation.

That is why I am closely observing activities in that area, and most
probably the missing context that left you wandering why I participate in
the discussions on these patches at all. Hopefully this explanations
removes some of your dilemmas.

Best regards,
Aleksandar