From: Andrew Cooper <email@example.com>
To: Stefano Stabellini <firstname.lastname@example.org>
Cc: Luca Fancellu <email@example.com>,
<firstname.lastname@example.org>, George Dunlap <email@example.com>,
Ian Jackson <firstname.lastname@example.org>, Jan Beulich <email@example.com>,
Julien Grall <firstname.lastname@example.org>, Wei Liu <email@example.com>
Subject: Re: [PATCH 0/3] Use Doxygen and sphinx for html documentation
Date: Wed, 7 Apr 2021 12:15:56 +0100 [thread overview]
Message-ID: <firstname.lastname@example.org> (raw)
On 06/04/2021 22:24, Stefano Stabellini wrote:
> On Tue, 6 Apr 2021, Andrew Cooper wrote:
>> On 06/04/2021 11:36, Luca Fancellu wrote:
>>> 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 must 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):
>>> make -C xen XEN_TARGET_ARCH="arm64" CROSS_COMPILE="aarch64-linux-gnu-" menuconfig
>>> make -C xen XEN_TARGET_ARCH="arm64" CROSS_COMPILE="aarch64-linux-gnu-"
>>> 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.
>> Do you have a sample rendered output?
>> The plan was to try and use Linux's kernel-doc plugin for Sphinx, which
>> is very doxygen-like. Did you experiment with this option?
> As you probably know the end goal for Luca (and the Xen FuSa SIG as a
> whole) is to generate all FuSa documents, including requirements docs,
> interface docs, etc.
> FuSa requires us to follow the famous V model, where the high level
> requirements are linked to the lower level requirements, which are
> linked to the interface docs, which are linked all the way down to the
> Maintaining the linking is difficult and typically done with expensive
> proprietary FuSa tools.
> Fortunately, an engineer working with the Zephyr project developed a set
> of scripts for Doxygen that are able to generate the required FuSa docs
> and also links from in-code comments and markdown/rst docs in the tree.
> This is great work, and in the FuSa SIG we thought it would be best to
> align ourselves with Zephyr to be able to pull our efforts together on
> the tooling side instead of doing the same thing again on our own.
> This is the reason why we ended up with Doxygen.
So are we're saying that Doxygen is a hard dependency because there is
an extension for Doxygen to generate other safety docs?
next prev parent reply other threads:[~2021-04-07 11:16 UTC|newest]
Thread overview: 34+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-04-06 10:36 [PATCH 0/3] Use Doxygen and sphinx for html documentation Luca Fancellu
2021-04-06 10:36 ` [PATCH 1/3] docs: add doxygen support " Luca Fancellu
2021-04-06 10:36 ` [PATCH 2/3] docs: hypercalls sphinx skeleton for generated html Luca Fancellu
2021-04-06 10:36 ` [PATCH 3/3] docs/doxygen: doxygen documentation for grant_table.h Luca Fancellu
2021-04-06 11:19 ` Jan Beulich
2021-04-06 21:46 ` Stefano Stabellini
2021-04-07 8:10 ` Jan Beulich
2021-04-07 8:42 ` Luca Fancellu
2021-04-07 8:58 ` Jan Beulich
2021-04-07 21:26 ` Stefano Stabellini
2021-04-08 5:59 ` Jan Beulich
2021-04-08 11:02 ` Luca Fancellu
2021-04-08 11:28 ` Jan Beulich
2021-04-08 11:40 ` Julien Grall
2021-04-08 11:50 ` Julien Grall
2021-04-08 13:13 ` Luca Fancellu
2021-04-08 11:58 ` Luca Fancellu
2021-04-07 13:13 ` Julien Grall
2021-04-07 13:19 ` Luca Fancellu
2021-04-07 13:56 ` Julien Grall
2021-04-07 14:51 ` Luca Fancellu
2021-04-07 15:19 ` Ian Jackson
2021-04-07 15:29 ` Bertrand Marquis
2021-04-07 15:54 ` Jan Beulich
2021-04-07 16:07 ` Bertrand Marquis
2021-04-07 15:55 ` Julien Grall
2021-04-07 16:06 ` Bertrand Marquis
2021-04-07 16:12 ` Ian Jackson
2021-04-06 11:53 ` [PATCH 0/3] Use Doxygen and sphinx for html documentation Andrew Cooper
2021-04-06 21:24 ` Stefano Stabellini
2021-04-07 11:15 ` Andrew Cooper [this message]
2021-04-07 13:05 ` Bertrand Marquis
2021-04-07 13:07 ` Julien Grall
2021-04-07 13:16 ` Luca Fancellu
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:
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
* 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).