From: Luca Fancellu <luca.fancellu@arm.com>
To: xen-devel@lists.xenproject.org
Cc: 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>,
Stefano Stabellini <sstabellini@kernel.org>, Wei Liu <wl@xen.org>
Subject: [PATCH v7 0/9] Use Doxygen and sphinx for html documentation
Date: Mon, 5 Jul 2021 11:50:54 +0100 [thread overview]
Message-ID: <20210705105103.14509-1-luca.fancellu@arm.com> (raw)
This serie introduce doxygen in the sphinx html docs generation.
One benefit is to keep most of the documentation in the source
files of xen so that it's more maintainable, on the other hand
there are some limitation of doxygen that should be addressed
modifying the current codebase (for example doxygen can't parse
anonymous structure/union).
To reproduce the documentation xen must be compiled because
most of the headers are generated on compilation time from
the makefiles.
Here follows the steps to generate the sphinx html docs, some
package may be required on your machine, everything is suggested
by the autoconf script.
Here I'm building the arm64 docs (the only introduced for now by
this serie):
./configure
make -C xen XEN_TARGET_ARCH="arm64" CROSS_COMPILE="aarch64-linux-gnu-" defconfig
make -C docs XEN_TARGET_ARCH="arm64" sphinx-html
now in docs/sphinx/html/ we have the generated docs starting
from the index.html page.
I've created a preview showing the html pages:
https://luca.fancellu.gitlab.io/xen-docs/hypercall-interfaces/arm64.html
The browser will show you a warning about the certificate, that's because
my gitlab username contains a dot, this is a known limitation of gitlab pages
so there is nothing to worry about.
Luca Fancellu (9):
docs: add doxygen configuration file
docs: add Xen png logo for the doxygen documentation
docs: add doxygen templates
m4/python: add function to docs_tool.m4 and new m4 module
docs: add checks to configure for sphinx and doxygen
docs: add doxygen preprocessor and related files
docs: Change Makefile and sphinx configuration for doxygen
docs: hypercalls sphinx skeleton for generated html
docs/doxygen: doxygen documentation for grant_table.h
.gitignore | 7 +
config/Docs.mk.in | 2 +
docs/Makefile | 47 +-
docs/conf.py | 43 +-
docs/configure | 258 ++
docs/configure.ac | 15 +
docs/hypercall-interfaces/arm32.rst | 32 +
docs/hypercall-interfaces/arm64.rst | 33 +
.../common/grant_tables.rst | 9 +
docs/hypercall-interfaces/index.rst.in | 7 +
docs/hypercall-interfaces/x86_64.rst | 32 +
docs/index.rst | 8 +
docs/xen-doxygen/customdoxygen.css | 36 +
docs/xen-doxygen/doxy-preprocessor.py | 116 +
docs/xen-doxygen/doxy_input.list | 1 +
docs/xen-doxygen/doxygen_include.h.in | 32 +
docs/xen-doxygen/footer.html | 21 +
docs/xen-doxygen/header.html | 56 +
docs/xen-doxygen/mainpage.md | 5 +
docs/xen-doxygen/xen_project_logo_165x67.png | Bin 0 -> 18223 bytes
docs/xen.doxyfile.in | 2316 +++++++++++++++++
m4/ax_python_module.m4 | 56 +
m4/docs_tool.m4 | 9 +
xen/include/public/grant_table.h | 459 ++--
24 files changed, 3412 insertions(+), 188 deletions(-)
create mode 100644 docs/hypercall-interfaces/arm32.rst
create mode 100644 docs/hypercall-interfaces/arm64.rst
create mode 100644 docs/hypercall-interfaces/common/grant_tables.rst
create mode 100644 docs/hypercall-interfaces/index.rst.in
create mode 100644 docs/hypercall-interfaces/x86_64.rst
create mode 100644 docs/xen-doxygen/customdoxygen.css
create mode 100755 docs/xen-doxygen/doxy-preprocessor.py
create mode 100644 docs/xen-doxygen/doxy_input.list
create mode 100644 docs/xen-doxygen/doxygen_include.h.in
create mode 100644 docs/xen-doxygen/footer.html
create mode 100644 docs/xen-doxygen/header.html
create mode 100644 docs/xen-doxygen/mainpage.md
create mode 100644 docs/xen-doxygen/xen_project_logo_165x67.png
create mode 100644 docs/xen.doxyfile.in
create mode 100644 m4/ax_python_module.m4
--
2.17.1
next reply other threads:[~2021-07-05 10:55 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-07-05 10:50 Luca Fancellu [this message]
2021-07-05 10:50 ` [PATCH v7 1/9] docs: add doxygen configuration file Luca Fancellu
2021-07-05 10:50 ` [PATCH v7 2/9] docs: add Xen png logo for the doxygen documentation Luca Fancellu
2021-07-05 10:50 ` [PATCH v7 3/9] docs: add doxygen templates Luca Fancellu
2021-07-05 10:50 ` [PATCH v7 4/9] m4/python: add function to docs_tool.m4 and new m4 module Luca Fancellu
2021-07-05 10:50 ` [PATCH v7 5/9] docs: add checks to configure for sphinx and doxygen Luca Fancellu
2021-07-05 10:51 ` [PATCH v7 6/9] docs: add doxygen preprocessor and related files Luca Fancellu
2021-07-05 10:51 ` [PATCH v7 7/9] docs: Change Makefile and sphinx configuration for doxygen Luca Fancellu
2021-07-05 10:51 ` [PATCH v7 8/9] docs: hypercalls sphinx skeleton for generated html Luca Fancellu
2021-07-05 10:51 ` [PATCH v7 9/9] docs/doxygen: doxygen documentation for grant_table.h Luca Fancellu
2021-07-05 13:03 ` Jan Beulich
2021-07-05 13:23 ` Luca Fancellu
2021-07-05 13:27 ` Jan Beulich
2021-07-06 8:38 ` Luca Fancellu
2021-07-05 14:20 ` Julien Grall
2021-07-06 8:44 ` Luca Fancellu
2021-07-07 13:24 ` Julien Grall
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=20210705105103.14509-1-luca.fancellu@arm.com \
--to=luca.fancellu@arm.com \
--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=sstabellini@kernel.org \
--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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.