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): >>> >>> ./configure >>> 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 > code. > > 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? ~Andrew
