From: Stefano Stabellini <sstabellini@kernel.org>
To: Luca Fancellu <luca.fancellu@arm.com>
Cc: Stefano Stabellini <sstabellini@kernel.org>,
xen-devel@lists.xenproject.org,
Bertrand Marquis <bertrand.marquis@arm.com>,
wei.chen@arm.com, Andrew Cooper <andrew.cooper3@citrix.com>,
George Dunlap <george.dunlap@citrix.com>,
Ian Jackson <iwj@xenproject.org>,
Jan Beulich <jbeulich@suse.com>, Julien Grall <julien@xen.org>,
Wei Liu <wl@xen.org>
Subject: Re: [PATCH v6 8/9] docs: hypercalls sphinx skeleton for generated html
Date: Thu, 1 Jul 2021 10:24:45 -0700 (PDT) [thread overview]
Message-ID: <alpine.DEB.2.21.2107011024220.9437@sstabellini-ThinkPad-T480s> (raw)
In-Reply-To: <D2BAA7F7-4396-4EE7-977B-AE300A50589D@arm.com>
On Thu, 1 Jul 2021, Luca Fancellu wrote:
> > On 24 Jun 2021, at 00:34, Stefano Stabellini <sstabellini@kernel.org> wrote:
> >
> > On Mon, 10 May 2021, Luca Fancellu wrote:
> >> Create a skeleton for the documentation about hypercalls
> >>
> >> Signed-off-by: Luca Fancellu <luca.fancellu@arm.com>
> >> ---
> >> v6 changes:
> >> - Now every platform has the same sections in .rst files
> >> ---
> >> .gitignore | 1 +
> >> docs/Makefile | 4 ++++
> >> docs/hypercall-interfaces/arm32.rst | 32 ++++++++++++++++++++++++++
> >> docs/hypercall-interfaces/arm64.rst | 32 ++++++++++++++++++++++++++
> >> docs/hypercall-interfaces/index.rst.in | 7 ++++++
> >> docs/hypercall-interfaces/x86_64.rst | 32 ++++++++++++++++++++++++++
> >> docs/index.rst | 8 +++++++
> >> 7 files changed, 116 insertions(+)
> >> create mode 100644 docs/hypercall-interfaces/arm32.rst
> >> create mode 100644 docs/hypercall-interfaces/arm64.rst
> >> create mode 100644 docs/hypercall-interfaces/index.rst.in
> >> create mode 100644 docs/hypercall-interfaces/x86_64.rst
> >>
> >> diff --git a/.gitignore b/.gitignore
> >> index d271e0ce6a..a9aab120ae 100644
> >> --- a/.gitignore
> >> +++ b/.gitignore
> >> @@ -64,6 +64,7 @@ docs/xen.doxyfile
> >> docs/xen.doxyfile.tmp
> >> docs/xen-doxygen/doxygen_include.h
> >> docs/xen-doxygen/doxygen_include.h.tmp
> >> +docs/hypercall-interfaces/index.rst
> >> extras/mini-os*
> >> install/*
> >> stubdom/*-minios-config.mk
> >> diff --git a/docs/Makefile b/docs/Makefile
> >> index 2f784c36ce..b02c3dfb79 100644
> >> --- a/docs/Makefile
> >> +++ b/docs/Makefile
> >> @@ -61,6 +61,9 @@ build: html txt pdf man-pages figs
> >> sphinx-html: $(DOXY_DEPS) $(DOXY_LIST_SOURCES)
> >> ifneq ($(SPHINXBUILD),no)
> >> $(DOXYGEN) xen.doxyfile
> >> + @echo "Generating hypercall-interfaces/index.rst"
> >> + @sed -e "s,@XEN_TARGET_ARCH@,$(XEN_TARGET_ARCH),g" \
> >> + hypercall-interfaces/index.rst.in > hypercall-interfaces/index.rst
> >
>
> Hi Stefano,
>
> > I take that this means we are going to generate docs only for the
> > architecture that we are building? So if we build for x86, then the docs
> > are for x86 (no arm32 and arm64 docs.) Is that right?
> >
> > Is that because Doxygen relies somehow on the compiler to extract data?
> > I am asking because if Doxygen doesn't rely on the compiler, then it
> > could probably generate the docs for all architectures in one go?
>
> Doxygen rely on the headers generated from the KConfig system to properly solve
> the preprocessor step, for that reason here we need that.
>
> It can be improved for sure, but it needs to call a defconfig for each architecture and
> have separate Doxygen-output folders for each one, then on the rst files you can choose
> from which arch you want the data.
>
> I think this step can be done in a future serie.
OK. Maybe add a note about this to one of the commit messages.
> >
> >
> >
> >> XEN_ROOT=$(realpath $(XEN_ROOT)) $(SPHINXBUILD) -b html . sphinx/html
> >> else
> >> @echo "Sphinx is not installed; skipping sphinx-html documentation."
> >> @@ -108,6 +111,7 @@ clean: clean-man-pages
> >> rm -f xen.doxyfile.tmp
> >> rm -f xen-doxygen/doxygen_include.h
> >> rm -f xen-doxygen/doxygen_include.h.tmp
> >> + rm -f hypercall-interfaces/index.rst
> >>
> >> .PHONY: distclean
> >> distclean: clean
> >> diff --git a/docs/hypercall-interfaces/arm32.rst b/docs/hypercall-interfaces/arm32.rst
> >> new file mode 100644
> >> index 0000000000..6762d9fc7c
> >> --- /dev/null
> >> +++ b/docs/hypercall-interfaces/arm32.rst
> >> @@ -0,0 +1,32 @@
> >> +.. SPDX-License-Identifier: CC-BY-4.0
> >> +
> >> +Hypercall Interfaces - arm32
> >> +============================
> >> +
> >> +Starting points
> >> +---------------
> >> +.. toctree::
> >> + :maxdepth: 2
> >> +
> >> +
> >> +
> >> +Functions
> >> +---------
> >> +
> >> +
> >> +Structs
> >> +-------
> >> +
> >> +
> >> +Enums and sets of #defines
> >> +--------------------------
> >> +
> >> +
> >> +Typedefs
> >> +--------
> >> +
> >> +
> >> +Enum values and individual #defines
> >> +-----------------------------------
> >> +
> >> +
> >> diff --git a/docs/hypercall-interfaces/arm64.rst b/docs/hypercall-interfaces/arm64.rst
> >> new file mode 100644
> >> index 0000000000..5e701a2adc
> >> --- /dev/null
> >> +++ b/docs/hypercall-interfaces/arm64.rst
> >> @@ -0,0 +1,32 @@
> >> +.. SPDX-License-Identifier: CC-BY-4.0
> >> +
> >> +Hypercall Interfaces - arm64
> >> +============================
> >> +
> >> +Starting points
> >> +---------------
> >> +.. toctree::
> >> + :maxdepth: 2
> >> +
> >> +
> >> +
> >> +Functions
> >> +---------
> >> +
> >> +
> >> +Structs
> >> +-------
> >> +
> >> +
> >> +Enums and sets of #defines
> >> +--------------------------
> >> +
> >> +
> >> +Typedefs
> >> +--------
> >> +
> >> +
> >> +Enum values and individual #defines
> >> +-----------------------------------
> >> +
> >> +
> >> diff --git a/docs/hypercall-interfaces/index.rst.in b/docs/hypercall-interfaces/index.rst.in
> >> new file mode 100644
> >> index 0000000000..e4dcc5db8d
> >> --- /dev/null
> >> +++ b/docs/hypercall-interfaces/index.rst.in
> >> @@ -0,0 +1,7 @@
> >> +.. SPDX-License-Identifier: CC-BY-4.0
> >> +
> >> +Hypercall Interfaces
> >> +====================
> >> +
> >> +.. toctree::
> >> + @XEN_TARGET_ARCH@
> >> diff --git a/docs/hypercall-interfaces/x86_64.rst b/docs/hypercall-interfaces/x86_64.rst
> >> new file mode 100644
> >> index 0000000000..59e948900c
> >> --- /dev/null
> >> +++ b/docs/hypercall-interfaces/x86_64.rst
> >> @@ -0,0 +1,32 @@
> >> +.. SPDX-License-Identifier: CC-BY-4.0
> >> +
> >> +Hypercall Interfaces - x86_64
> >> +=============================
> >> +
> >> +Starting points
> >> +---------------
> >> +.. toctree::
> >> + :maxdepth: 2
> >> +
> >> +
> >> +
> >> +Functions
> >> +---------
> >> +
> >> +
> >> +Structs
> >> +-------
> >> +
> >> +
> >> +Enums and sets of #defines
> >> +--------------------------
> >> +
> >> +
> >> +Typedefs
> >> +--------
> >> +
> >> +
> >> +Enum values and individual #defines
> >> +-----------------------------------
> >> +
> >> +
> >> diff --git a/docs/index.rst b/docs/index.rst
> >> index b75487a05d..52226a42d8 100644
> >> --- a/docs/index.rst
> >> +++ b/docs/index.rst
> >> @@ -53,6 +53,14 @@ kind of development environment.
> >> hypervisor-guide/index
> >>
> >>
> >> +Hypercall Interfaces documentation
> >> +----------------------------------
> >> +
> >> +.. toctree::
> >> + :maxdepth: 2
> >> +
> >> + hypercall-interfaces/index
> >> +
> >> Miscellanea
> >> -----------
> >>
> >> --
> >> 2.17.1
>
next prev parent reply other threads:[~2021-07-01 17:25 UTC|newest]
Thread overview: 30+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-05-10 8:40 [PATCH v6 0/9] Use Doxygen and sphinx for html documentation Luca Fancellu
2021-05-10 8:40 ` [PATCH v6 1/9] docs: add doxygen configuration file Luca Fancellu
2021-05-10 8:40 ` [PATCH v6 2/9] docs: add Xen png logo for the doxygen documentation Luca Fancellu
2021-05-10 8:40 ` [PATCH v6 3/9] docs: add doxygen templates Luca Fancellu
2021-05-10 8:41 ` [PATCH v6 4/9] m4/python: add function to docs_tool.m4 and new m4 module Luca Fancellu
2021-07-02 22:22 ` Stefano Stabellini
2021-05-10 8:41 ` [PATCH v6 5/9] docs: add checks to configure for sphinx and doxygen Luca Fancellu
2021-07-02 22:22 ` Stefano Stabellini
2021-05-10 8:41 ` [PATCH v6 6/9] docs: add doxygen preprocessor and related files Luca Fancellu
2021-06-23 22:03 ` Stefano Stabellini
2021-07-01 13:04 ` Luca Fancellu
2021-07-01 17:36 ` Stefano Stabellini
2021-05-10 8:41 ` [PATCH v6 7/9] docs: Change Makefile and sphinx configuration for doxygen Luca Fancellu
2021-06-23 23:33 ` Stefano Stabellini
2021-07-01 13:36 ` Luca Fancellu
2021-07-01 17:43 ` Stefano Stabellini
2021-07-02 9:30 ` Luca Fancellu
2021-07-02 22:23 ` Stefano Stabellini
2021-07-05 9:41 ` Luca Fancellu
2021-05-10 8:41 ` [PATCH v6 8/9] docs: hypercalls sphinx skeleton for generated html Luca Fancellu
2021-06-23 23:34 ` Stefano Stabellini
2021-07-01 14:06 ` Luca Fancellu
2021-07-01 17:24 ` Stefano Stabellini [this message]
2021-05-10 8:41 ` [PATCH v6 9/9] docs/doxygen: doxygen documentation for grant_table.h Luca Fancellu
2021-06-23 23:34 ` Stefano Stabellini
2021-07-01 14:19 ` Luca Fancellu
2021-07-01 17:44 ` Stefano Stabellini
2021-07-02 11:01 ` Luca Fancellu
2021-07-02 20:21 ` Stefano Stabellini
2021-06-07 16:24 ` [PATCH v6 0/9] Use Doxygen and sphinx for html documentation Luca Fancellu
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=alpine.DEB.2.21.2107011024220.9437@sstabellini-ThinkPad-T480s \
--to=sstabellini@kernel.org \
--cc=andrew.cooper3@citrix.com \
--cc=bertrand.marquis@arm.com \
--cc=george.dunlap@citrix.com \
--cc=iwj@xenproject.org \
--cc=jbeulich@suse.com \
--cc=julien@xen.org \
--cc=luca.fancellu@arm.com \
--cc=wei.chen@arm.com \
--cc=wl@xen.org \
--cc=xen-devel@lists.xenproject.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).