Skip to content

Use Doxygen and sphinx for html documentation

Luca Fancellu xen-devel 7 versions – In review

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v7 Latest9 patches 7 repliesIn review
  2. v69 patches 20 repliesSuperseded
  3. v53 patches 11 repliesSuperseded
Earlier versions · 4
VersionPostedPatchesRepliesStatus
v43 patches5 repliesSuperseded
v33 patches8 repliesSuperseded
v23 patches8 repliesSuperseded
v13 patches30 repliesSuperseded

Patches in v7 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/9docs: add doxygen configuration filedocs/xen.doxyfile.in+2316 -00 replies
2/9docs: add Xen png logo for the doxygen documentationdocs/xen-doxygen/xen_project_logo_165x67.png+0 -00 replies
3/9docs: add doxygen templatesdocs/xen-doxygen/customdoxygen.css docs/xen-doxygen/footer.html docs/xen-doxygen/header.html +1 more+118 -00 replies
4/9m4/python: add function to docs_tool.m4 and new m4 modulem4/ax_python_module.m4 m4/docs_tool.m4+65 -00 replies
5/9docs: add checks to configure for sphinx and doxygenconfig/Docs.mk.in docs/configure docs/configure.ac+275 -00 replies
6/9docs: add doxygen preprocessor and related filesdocs/xen-doxygen/doxy-preprocessor.py docs/xen-doxygen/doxy_input.list docs/xen-doxygen/doxygen_include.h.in+148 -00 replies
7/9docs: Change Makefile and sphinx configuration for doxygen.gitignore docs/Makefile docs/conf.py+86 -60 replies
8/9docs: hypercalls sphinx skeleton for generated html.gitignore docs/Makefile docs/hypercall-interfaces/arm32.rst +4 more+116 -00 replies
9/9docs/doxygen: doxygen documentation for grant_table.hdocs/hypercall-interfaces/arm64.rst docs/hypercall-interfaces/common/grant_tables.rst docs/xen-doxygen/doxy_input.list +1 more+288 -1827 replies

Reviews trailers per patch

5 of 9 patches have a Reviewed-by or Acked-by.

PatchStefano Stabellini
1/9A-b
2/9A-b
3/9A-b
4/9A-b
5/9A-b
6/9
7/9
8/9
9/9

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.

Read the v7 thread

Cover letter [PATCH v7 0/9] Use Doxygen and sphinx for html documentation

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
Signature · 1 line
2.17.1