From patchwork Mon Jul 5 10:50:54 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Fancellu X-Patchwork-Id: 12358833 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-11.8 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id D9BD1C07E99 for ; Mon, 5 Jul 2021 10:55:30 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id A687A6141C for ; Mon, 5 Jul 2021 10:55:30 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org A687A6141C Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=arm.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from list by lists.xenproject.org with outflank-mailman.150095.277577 (Exim 4.92) (envelope-from ) id 1m0MG0-0003rX-Hx; Mon, 05 Jul 2021 10:55:20 +0000 X-Outflank-Mailman: Message body and most headers restored to incoming version Received: by outflank-mailman (output) from mailman id 150095.277577; Mon, 05 Jul 2021 10:55:20 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1m0MG0-0003rQ-Eh; Mon, 05 Jul 2021 10:55:20 +0000 Received: by outflank-mailman (input) for mailman id 150095; Mon, 05 Jul 2021 10:55:19 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1m0MFz-0003rB-DL for xen-devel@lists.xenproject.org; Mon, 05 Jul 2021 10:55:19 +0000 Received: from foss.arm.com (unknown [217.140.110.172]) by us1-rack-iad1.inumbo.com (Halon) with ESMTP id e51cca4b-a6c1-4dc9-af93-d15b89961689; Mon, 05 Jul 2021 10:55:18 +0000 (UTC) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id E3B781042; Mon, 5 Jul 2021 03:55:17 -0700 (PDT) Received: from e125770.cambridge.arm.com (e125770.cambridge.arm.com [10.1.197.16]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 90D943F5A1; Mon, 5 Jul 2021 03:55:16 -0700 (PDT) X-BeenThere: xen-devel@lists.xenproject.org List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Precedence: list Sender: "Xen-devel" X-Inumbo-ID: e51cca4b-a6c1-4dc9-af93-d15b89961689 From: Luca Fancellu To: xen-devel@lists.xenproject.org Cc: bertrand.marquis@arm.com, wei.chen@arm.com, Andrew Cooper , George Dunlap , Ian Jackson , Jan Beulich , Julien Grall , Stefano Stabellini , Wei Liu Subject: [PATCH v7 0/9] Use Doxygen and sphinx for html documentation Date: Mon, 5 Jul 2021 11:50:54 +0100 Message-Id: <20210705105103.14509-1-luca.fancellu@arm.com> X-Mailer: git-send-email 2.17.1 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