From mboxrd@z Thu Jan 1 00:00:00 1970 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=-10.0 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, LOTS_OF_MONEY,MAILING_LIST_MULTI,MONEY_NOHTML,NORMAL_HTTP_TO_IP, NUMERIC_HTTP_ADDR,SPF_HELO_NONE,SPF_PASS,T_MONEY_PERCENT,UNPARSEABLE_RELAY, URIBL_BLOCKED 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 70596C433B4 for ; Wed, 5 May 2021 10:52:27 +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 9E0B5613BC for ; Wed, 5 May 2021 10:52:26 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 9E0B5613BC 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.122991.232027 (Exim 4.92) (envelope-from ) id 1leF8W-0003rU-A3; Wed, 05 May 2021 10:52:12 +0000 X-Outflank-Mailman: Message body and most headers restored to incoming version Received: by outflank-mailman (output) from mailman id 122991.232027; Wed, 05 May 2021 10:52:12 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1leF8W-0003rN-6h; Wed, 05 May 2021 10:52:12 +0000 Received: by outflank-mailman (input) for mailman id 122991; Wed, 05 May 2021 10:52:11 +0000 Received: from all-amaz-eas1.inumbo.com ([34.197.232.57] helo=us1-amaz-eas2.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1leF8V-0003rF-2E for xen-devel@lists.xenproject.org; Wed, 05 May 2021 10:52:11 +0000 Received: from EUR01-VE1-obe.outbound.protection.outlook.com (unknown [40.107.14.57]) by us1-amaz-eas2.inumbo.com (Halon) with ESMTPS id 0617f20a-4073-49d1-96d5-d206e008667c; Wed, 05 May 2021 10:51:59 +0000 (UTC) Received: from AM5PR0701CA0054.eurprd07.prod.outlook.com (2603:10a6:203:2::16) by VI1PR08MB2784.eurprd08.prod.outlook.com (2603:10a6:802:25::17) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4087.38; Wed, 5 May 2021 10:51:46 +0000 Received: from VE1EUR03FT010.eop-EUR03.prod.protection.outlook.com (2603:10a6:203:2:cafe::92) by AM5PR0701CA0054.outlook.office365.com (2603:10a6:203:2::16) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4129.9 via Frontend Transport; Wed, 5 May 2021 10:51:46 +0000 Received: from 64aa7808-outbound-1.mta.getcheckrecipient.com (63.35.35.123) by VE1EUR03FT010.mail.protection.outlook.com (10.152.18.113) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4108.25 via Frontend Transport; Wed, 5 May 2021 10:51:46 +0000 Received: ("Tessian outbound 8ca198b738d3:v91"); Wed, 05 May 2021 10:51:46 +0000 Received: from 3183eb751811.1 by 64aa7808-outbound-1.mta.getcheckrecipient.com id C2E83D08-C077-4856-9140-0FBAA0644FA4.1; Wed, 05 May 2021 10:51:37 +0000 Received: from EUR05-VI1-obe.outbound.protection.outlook.com by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id 3183eb751811.1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384); Wed, 05 May 2021 10:51:37 +0000 Received: from VI1PR08MB3629.eurprd08.prod.outlook.com (2603:10a6:803:7f::25) by VI1PR08MB3758.eurprd08.prod.outlook.com (2603:10a6:803:bd::26) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4087.41; Wed, 5 May 2021 10:51:29 +0000 Received: from VI1PR08MB3629.eurprd08.prod.outlook.com ([fe80::4502:9762:8b3b:63d9]) by VI1PR08MB3629.eurprd08.prod.outlook.com ([fe80::4502:9762:8b3b:63d9%4]) with mapi id 15.20.4087.044; Wed, 5 May 2021 10:51:29 +0000 Received: from smtpclient.apple (82.8.129.65) by LO4P123CA0281.GBRP123.PROD.OUTLOOK.COM (2603:10a6:600:195::16) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4108.25 via Frontend Transport; Wed, 5 May 2021 10:51:28 +0000 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: 0617f20a-4073-49d1-96d5-d206e008667c DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=SQuhihuktO+p7OS9loCQjTVC8zQWtC2OYhyNMnJssBA=; b=7/e25+cagESvhNQJmJ+yhAIa3lvId6umLEkMZpezXe4uYFmCSw1TBN3IJFlWCmGcZoFu3jD6UxhZnJbDf09LsS2UJNZyh2Fo0NrGl6w5fY3kRU1XkJ3Ej0LWAYsr7+7FYTQmss26pImrGvBM0weZDoZiNVxz8j+3Iglo56XOTqk= X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 63.35.35.123) smtp.mailfrom=arm.com; lists.xenproject.org; dkim=pass (signature was verified) header.d=armh.onmicrosoft.com;lists.xenproject.org; dmarc=pass action=none header.from=arm.com; Received-SPF: Pass (protection.outlook.com: domain of arm.com designates 63.35.35.123 as permitted sender) receiver=protection.outlook.com; client-ip=63.35.35.123; helo=64aa7808-outbound-1.mta.getcheckrecipient.com; X-CheckRecipientChecked: true X-CR-MTA-CID: ca612930dbba5433 X-CR-MTA-TID: 64aa7808 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=jjK8XdhLopSsRS4BAD3l/tmNSQXUi77RIht0l4qF7Z2V0e6BhRpvn8wEe0DUar54UTJVphZee81tg+yIcOkUDqtKWq6v6IFadvbTfPoGIS6bzPUesCEupu8+iBLurNA6N409C1RFZLVT3cKnuZYexJhOAHl9C5oyIHxn8iJlW9TVR2nk1sKgo2Jr8SIHPfxh2d8tG63KgqdzLbH/6N7WSp08xjfmEX8k58svdMFuy5KReZ7qcbrWKZw4XLRx5XAbxQbvKUL+DdG8p2pwjBC9NhCa596CDsDxrBbbbHs24WSuyNOtu46zyGWGXdCyr0olZ//m8MvmaUja7cCmyDeC6Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=SQuhihuktO+p7OS9loCQjTVC8zQWtC2OYhyNMnJssBA=; b=lP/7t8Qs6HSOpCz3H8teMN5xusMvibcNiYuWwu5XoN9xVF8F9fl+VOuP8tqBmLnoRaaNOn+Qv3JnCZei5Qb6hZdRgZdTXvhyD0905bfWiBYvntYu1YIeAvd7vD3GiXeQcj7IgIPdxoic6vXkBy2RWuPS+QsodzGnqLZmx+EmnkpWO2m9TD9A2pdCEqNbP0xs3t+7+UVmfBDFGc0wlnwAXjeyN9UWwri+NdtMVF81+fVwnwt6qmaY4mFx1pwX0FalD+J3uPCuDAPefv6bJpIaDUEU0H7L+yrsZkeXbdK2U8L+cRDnvRURz6YJjCyPERWMQ7L3EJp0ljMVqV3QfSvBTQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=arm.com; dmarc=pass action=none header.from=arm.com; dkim=pass header.d=arm.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; s=selector2-armh-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=SQuhihuktO+p7OS9loCQjTVC8zQWtC2OYhyNMnJssBA=; b=7/e25+cagESvhNQJmJ+yhAIa3lvId6umLEkMZpezXe4uYFmCSw1TBN3IJFlWCmGcZoFu3jD6UxhZnJbDf09LsS2UJNZyh2Fo0NrGl6w5fY3kRU1XkJ3Ej0LWAYsr7+7FYTQmss26pImrGvBM0weZDoZiNVxz8j+3Iglo56XOTqk= Authentication-Results-Original: kernel.org; dkim=none (message not signed) header.d=none;kernel.org; dmarc=none action=none header.from=arm.com; Content-Type: text/plain; charset=utf-8 Subject: Re: [PATCH v5 1/3] docs: add doxygen support for html documentation From: Luca Fancellu In-Reply-To: Date: Wed, 5 May 2021 11:51:22 +0100 Cc: xen-devel@lists.xenproject.org, Bertrand Marquis , wei.chen@arm.com, Andrew Cooper , George Dunlap , Ian Jackson , Jan Beulich , Julien Grall , Wei Liu Content-Transfer-Encoding: quoted-printable Message-Id: References: <20210504133145.767-1-luca.fancellu@arm.com> <20210504133145.767-2-luca.fancellu@arm.com> To: Stefano Stabellini X-Mailer: Apple Mail (2.3654.80.0.2.43) X-Originating-IP: [82.8.129.65] X-ClientProxiedBy: LO4P123CA0281.GBRP123.PROD.OUTLOOK.COM (2603:10a6:600:195::16) To VI1PR08MB3629.eurprd08.prod.outlook.com (2603:10a6:803:7f::25) MIME-Version: 1.0 X-MS-Exchange-MessageSentRepresentingType: 1 X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: bcea167d-aac7-4fa3-463d-08d90fb3c72e X-MS-TrafficTypeDiagnostic: VI1PR08MB3758:|VI1PR08MB2784: X-MS-Exchange-Transport-Forked: True X-Microsoft-Antispam-PRVS: x-checkrecipientrouted: true NoDisclaimer: true X-MS-Oob-TLC-OOBClassifiers: OLM:6430;OLM:6430; X-MS-Exchange-SenderADCheck: 1 X-Microsoft-Antispam-Untrusted: BCL:0; X-Microsoft-Antispam-Message-Info-Original: MLOc42lEvu3XUmDCLYhG1gect2j84R6Ua//1LvDom1gq4funfxi1HQpgBqMwIMdlm/i3nCBvfSR57ICSbJ215w1sLkPilYaoAKP1SNLrng+lU6Cm2JGf/FiTRFICeUGcy/Z2VXkzLEDc9K31gtlwfUQrLsCpPDE3dOFjVl5AnIDxW/bkbhBSUDvlHUBWx11/pDd+P9u9Bt46RbYjPi8gXvaZDG6x5o1Lo+Z4spBq3EGSwqVn+cUrSMX7hESayXyzJJaIiiiTwrx83RoQ3AMccUBagUzqeSybAtAJTkVeps8CBGMtk19QSdf/nx55s/iG8UGvuXM6hFsTLumriH251S4G5sw8KFcFzrr1PrRvmxt7pnIkbrudykAvqUJ/RHQaeycoOswzLv29eXEIDkfq2cAYlkB5DebxA9vRnqpraL4bzgDxEg9OymxK8hJoxNTKlfkOHt4zVM6idbYMoCXVceP9CI9gvPpsF0fM8lweiw7Qz5iXeKXCY12F9roC4O8DxwwoCxb9FWJnsAIglanNhtw3WcpG7rTXlDF1Nutpk7vjwvp9+h91fOokR4xdcVLiTcbkQHT595odK46hNApoiaJ2Gug4pWFLEiiuD0omINEyi1Wjpr8EB0UA7vJ5IWkQZloDoJPM4vZx1fQ8HAqNWTtjuQkf1ScYuK9NlY54jnuxHxDWC7uZRC0Q/3R8MLfMWECt9PECH71hkqZ5pgyhHxyunsDopKORyu/ua+NqJID7fJv1UOI5w7BY5HlWxTZJ/K0bfxf6zWyBgNVnuIkrS2cjs/mEFBnh7c5G5Whr79gkhEN+TzQWB85KpHvzth7cMIaFze4hp1AWJzLOf51W8pFpbeTEMy2rV6C1EC3sCsyDMYbjqMwGj3fIHHH3E+l/ X-Forefront-Antispam-Report-Untrusted: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:VI1PR08MB3629.eurprd08.prod.outlook.com;PTR:;CAT:NONE;SFS:(4636009)(39860400002)(136003)(346002)(396003)(376002)(366004)(66574015)(4326008)(166002)(83380400001)(478600001)(956004)(44832011)(186003)(45080400002)(21615005)(38350700002)(2616005)(6512007)(86362001)(6486002)(6916009)(26005)(16799955002)(2906002)(30864003)(66556008)(66946007)(66476007)(16526019)(36756003)(316002)(19273905006)(966005)(52116002)(5660300002)(38100700002)(33656002)(54906003)(8936002)(53546011)(6506007)(8676002)(6666004)(292474003)(21314003)(45980500001)(579004)(559001)(563064011)(460985005);DIR:OUT;SFP:1101; X-MS-Exchange-AntiSpam-MessageData: =?utf-8?B?TmtrdmNKMDJOMXIwaVZyS3NOMVRTR3EybVN5RlhFWnJkaEtPVGczbGh2OXgy?= =?utf-8?B?YTJYNUhMMU1QY056RFp4c3prZnNTNW16M3VUcTR0SEwzZ2xRazhFUm4zMEJL?= =?utf-8?B?UFAycnJkQmRVWHNxYWFxem4xU2FudnJEL0VjRW42RnNMR1lqc0FjUkVFZ1J3?= =?utf-8?B?ZGpSZTltZDlVYjBBUUcxMXU2Mi92a1JTK05GOHZnbkRmanU4Y1pWblJ5SnV4?= =?utf-8?B?NGQyaUhKSnJpUEYwL3BaZjJOdkpNMXRPbUtHU0hjbjU4d2xzRERmRG05cTFX?= =?utf-8?B?VDZkbWtxcHpGNWpFVDVrQjB6MmZyc21XODlRdnZ5MXhTUmQybThmd2VUdFhp?= =?utf-8?B?M2h3N1dPWjdpQkpja0ZuVFlGSVl0SldDaEJ1MWQyUHQzWjJlazBNWEMrT3F0?= =?utf-8?B?VVBEaStKa0RhVnRRL1pQUHBIS2x0M2Rwd05UMVJuZEdMY1BPRVpoSHgzeWRx?= =?utf-8?B?OG9FKy94TkFoZS8xTHNpb0JVSk5xMFgrTGNUK3QrRTJBZ0lnL0ZEYVBRdHo4?= =?utf-8?B?UTlLdFlxMEh6dndoMTM1NjlyUDlUSnVnMHRuSGpTNlY4VS96aDgrM0dZUXc5?= =?utf-8?B?OVdsQVQzZG9aNGxrY3ZlamtWeDg4WGUzdnIrY1BZcEhZdUFtMERPMTBMWWdx?= =?utf-8?B?N3AvbVZkMzl4eDJrK3B1RGlUallTczNLN0paYzg1Wk10N2FWWTBnRloyeFpL?= =?utf-8?B?NnNOQUo3SzBIZTBTbHNMdVZFYkllNVZPV0xuTWtEOVlxazF0ODFlaG1UbWlB?= =?utf-8?B?TUJyR0FOazBLdWIvSXdyT3Y3cWtFN1Jjc1RuOEsxTElXNGtVYWZ6RXVLUGU3?= =?utf-8?B?eFhOR2g3UDZCN1EwV2lzZm5nclBHdXNMTmZ6Zm5wZk9iNy9pTGY4cmJ3SFND?= =?utf-8?B?NFlQMlorVDZlcUJxcCtaVWFuT3F2Skx1WmxpYXBhc3MwbjJvTHR5b1VSZUpI?= =?utf-8?B?RGRpSjY0SUxZV3VwM0gvZXdVQ0t0L21oUWN5SEhpOUx3MW9QU3NJdzVucENi?= =?utf-8?B?YlpEajVBQ1JncW1SSmI0U0x2Z1ZLTHVGV1AwS2pKUmh4Uy9mSFF0WDUyNVFx?= =?utf-8?B?VHlUNy9PN2JBaVNURlhpSit1bmw5cHQrcUJoTzlzMWROQitScVIxYmJCQUxZ?= =?utf-8?B?emJnRUdzU3NJcGxtVTdrYWxDSS9vd0l2cUJsN1lWR2VWK05TUkZkWnpQQy84?= =?utf-8?B?Tlc1RmxScWdrY0NtcVM2aHJzdXdzc2VpaWhVWjVpd1JvdFlpbEdaYnY4ZktR?= =?utf-8?B?dHM2ZWYxZ0x3aHZqaDRWaXRMQW9UTkliM2tBUStyTjQ0b1NLV2dPSnFDeENt?= =?utf-8?B?QXc4VVpXRkpML3Q4QnNmdHZ1VXBxSGZJM2U2MWJuSXpaZFhTRzFJbmxBSFZt?= =?utf-8?B?Qkd3TTNjRFdDMzhjVklDczRHOVVtVEVDTnp0NmYyQ2I4aUY5eUZxVEpBSEZn?= =?utf-8?B?RjdtamE0YlRkREFxVHF1a2h5a3ZnVDJITGdsVHpudnJKblRwREN4SFpaV0Nv?= =?utf-8?B?NG1rd0ZLd2h3V2VrLzJPQnNrZ1hmZ3BCSlk3NzIyenBpdE9LaVpUZ3VhUnY2?= =?utf-8?B?cWFEeXJhTEZlV21DN2hDUXlLVXkyQ3dQTEFxMFdlNE1DSGhmZWhndEx0d0hm?= =?utf-8?B?YU5UNk04SDBiSmQ4cU1JOVhiWDRqSE1TTlF4d25NQW5iWVdraEU5L094alh2?= =?utf-8?B?L25SYzZIeFErKzFEU3V4OG4wWlNWMkJSemhzLzdLbzR0eU9CNW9tdVdUVGc4?= =?utf-8?Q?3tBH7bUsrTXru6mzV0icMfcnLQxqnxj+nEvsDc9?= X-MS-Exchange-Transport-CrossTenantHeadersStamped: VI1PR08MB3758 Original-Authentication-Results: kernel.org; dkim=none (message not signed) header.d=none;kernel.org; dmarc=none action=none header.from=arm.com; X-EOPAttributedMessage: 0 X-MS-Exchange-Transport-CrossTenantHeadersStripped: VE1EUR03FT010.eop-EUR03.prod.protection.outlook.com X-MS-Office365-Filtering-Correlation-Id-Prvs: bd9aac0f-1280-4bb6-514b-08d90fb3bcd6 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: 7x17Err4fUWUyEEQPlKxqHFpzl5AK0fI1Ed5Viqh5Zh18VeNWZv4Nh9HhgLffJEynlg10by8JI75XcR6WCiSzydhQmj/E/FJ+6lj0pMlRsPjMb1jONaY6y18OuHMADanEENG0lCrJJq6nS70kqdAoRHMlpt/FmvOp88Po7qSbIM3wSIGjrEirKGk2cfouT1CQJJkma32910OVLkhjNOMkHfzCGpkb1XLITjMPj8CHdlGfCr1VghMYPjYRGIlEjTSM2XIevtBk2VMm7EX+p8F2RdL23oLKe+YOu7BJ4qdkgaeEl9rOBzhaXDQdjsLwTptKZv+Q4xBa4YKAv2yOakZa7CiXxdPm6idlbPzGsVb/3NUxppTAUVjz7byH5O7nkAmbTGoDQdfFuHznHOetFl5UAlaDDgT6p/0FzEZm4NLAiw/FTtSZXNC2gOtOfookH1vvcfh2kbmTHcvSf7uHSNT5l1LKuzfhyHumDUpGGS3SspmJTFjUfakoLo2/OgK3PjXiXPfwsazPYsHNvBfg8RFJmTvlU5WjM1xeXlTf9Vin1uXsSM1O2MiaSbvzEZUA5aXzhjb8JQpR5knM2Q0YUQER+RixCpHviVgqRWfNo4ud4lLhy09TwnlZ0vLolMb6QXa/lCJnsRbzLPhPvVF3bTNDeCngvqx1nCWZp5MKGf6HSjEJwZK1lZnHCU47CbcxjPeUE/q2Wiv3yGRUtMGJmMShOyl/TfRxQecRCsm9EZk03RKxCjxBvGhJmlx6bVNOMvvydI+Lfd5Qxp5V+/enwijDQU/su2ftiXSyhQfFBly13UmSlLyZsyhm/7INmXtj8N0RVSmISKOq3tPWjs7yCqqLA== X-Forefront-Antispam-Report: CIP:63.35.35.123;CTRY:IE;LANG:en;SCL:1;SRV:;IPV:CAL;SFV:NSPM;H:64aa7808-outbound-1.mta.getcheckrecipient.com;PTR:ec2-63-35-35-123.eu-west-1.compute.amazonaws.com;CAT:NONE;SFS:(4636009)(136003)(39860400002)(396003)(346002)(376002)(46966006)(36840700001)(21615005)(5660300002)(44832011)(6512007)(4326008)(36756003)(2616005)(86362001)(47076005)(45080400002)(30864003)(70586007)(336012)(70206006)(82310400003)(956004)(6862004)(26005)(2906002)(66574015)(316002)(54906003)(478600001)(6486002)(6506007)(53546011)(19273905006)(166002)(36860700001)(81166007)(83380400001)(186003)(16799955002)(8676002)(16526019)(966005)(8936002)(6666004)(82740400003)(356005)(33656002)(292474003)(21314003)(579004)(559001)(563064011)(460985005);DIR:OUT;SFP:1101; X-OriginatorOrg: arm.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 05 May 2021 10:51:46.3227 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: bcea167d-aac7-4fa3-463d-08d90fb3c72e X-MS-Exchange-CrossTenant-Id: f34e5979-57d9-4aaa-ad4d-b122a662184d X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=f34e5979-57d9-4aaa-ad4d-b122a662184d;Ip=[63.35.35.123];Helo=[64aa7808-outbound-1.mta.getcheckrecipient.com] X-MS-Exchange-CrossTenant-AuthSource: VE1EUR03FT010.eop-EUR03.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: VI1PR08MB2784 > On 4 May 2021, at 23:55, Stefano Stabellini wrot= e: >=20 > On Tue, 4 May 2021, Luca Fancellu wrote: >> Add doxygen support to build html documentation with sphinx, >> to do that the following modification are applied: >>=20 >> 1) Modify docs/configure.ac and consequently configure script >> to check, through the ./configure script, the presence in >> the system of the sphinx-build binary, if it is found then >> it checks also the presence of the doxygen binary, breathe >> and sphinx-rtd-theme python packages. >> Doxygen and the packages are required only if sphinx-build >> is found, otherwise the Makefile will simply skip the >> sphinx html generation. >> The ax_python_module.m4 support is needed to check for >> python packages. >> 2) Add doxygen templates and configuration file >> 3) Modify docs/Makefile to call in sequence doxygen and >> sphinx-build, the doxygen configuration file will be >> modified to include the xen absolute path and >> a list of header to parse. >> A doxygen_input.h file is generated to include every >> header listed in the doxy_input.list file. >> 4) Add preprocessor called by doxygen before parsing headers, >> it will include in every header a doxygen_include.h file >> that provides missing defines and includes that are >> usually passed by the compiler. >=20 > This is clearly is a gargantuan work! Thank you so much! >=20 > Is there a way we can split this patch somehow? Given the nature of the > work, obvious we can't do a line-by-line review of everything, but I > think it would be good to split it so that we can more easily ack parts > of it and review others. >=20 > For instance something like the following: >=20 > - one patch for docs/xen.doxyfile.in for which you can already add my > acked-by judging by the output[1] > - one patch to add the png image, also add my acked-by > - one patch for mainpage.md, header.html, footer.html, and > customdoxygen.css, I think they can all be on a single patch and have > my acked-by > - one patch to add the new m4 macros under m4/ > - one patch with changes to docs/configure.ac, docs/configure, > config/Docs.mk.in > - one patch with doxy-preprocessor.py, doxy_input.list, > doxygen_include.h.in > - one patch with changes to docs/Makefile and docs/conf.py >=20 > Does this sound reasonable to you? Hi Stefano, Yes I=E2=80=99ll split the patch and I=E2=80=99ll push everything in the v6= . Cheers, Luca >=20 >=20 > [1] https://luca.fancellu.gitlab.io/xen-docs/hypercall-interfaces/arm64/g= rant_tables.html >=20 >=20 >> Signed-off-by: Luca Fancellu >> --- >> v4 changes: >> - create alias @keepindent/@endkeepindent for the doxygen >> command @code/@endcode >> v3 changes: >> - add preprocessor to handle missing defines and anonymous >> structs/unions before doxygen parsing >> - modification to Makefile to handle the new process >> v2 changes: >> - Fix bug in Makefile when sphinx is not found in the system >> --- >> .gitignore | 6 + >> config/Docs.mk.in | 2 + >> docs/Makefile | 42 +- >> docs/conf.py | 48 +- >> docs/configure | 258 ++ >> docs/configure.ac | 15 + >> docs/xen-doxygen/customdoxygen.css | 36 + >> docs/xen-doxygen/doxy-preprocessor.py | 110 + >> docs/xen-doxygen/doxy_input.list | 0 >> 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 + >> 17 files changed, 3006 insertions(+), 6 deletions(-) >> 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 >>=20 >> diff --git a/.gitignore b/.gitignore >> index 1c2fa1530b..d271e0ce6a 100644 >> --- a/.gitignore >> +++ b/.gitignore >> @@ -58,6 +58,12 @@ docs/man7/ >> docs/man8/ >> docs/pdf/ >> docs/txt/ >> +docs/doxygen-output >> +docs/sphinx >> +docs/xen.doxyfile >> +docs/xen.doxyfile.tmp >> +docs/xen-doxygen/doxygen_include.h >> +docs/xen-doxygen/doxygen_include.h.tmp >> extras/mini-os* >> install/* >> stubdom/*-minios-config.mk >> diff --git a/config/Docs.mk.in b/config/Docs.mk.in >> index e76e5cd5ff..dfd4a02838 100644 >> --- a/config/Docs.mk.in >> +++ b/config/Docs.mk.in >> @@ -7,3 +7,5 @@ POD2HTML :=3D @POD2HTML@ >> POD2TEXT :=3D @POD2TEXT@ >> PANDOC :=3D @PANDOC@ >> PERL :=3D @PERL@ >> +SPHINXBUILD :=3D @SPHINXBUILD@ >> +DOXYGEN :=3D @DOXYGEN@ >> diff --git a/docs/Makefile b/docs/Makefile >> index 8de1efb6f5..2f784c36ce 100644 >> --- a/docs/Makefile >> +++ b/docs/Makefile >> @@ -17,6 +17,18 @@ TXTSRC-y :=3D $(sort $(shell find misc -name '*.txt' = -print)) >>=20 >> PANDOCSRC-y :=3D $(sort $(shell find designs/ features/ misc/ process/ s= pecs/ \( -name '*.pandoc' -o -name '*.md' \) -print)) >>=20 >> +# Directory in which the doxygen documentation is created >> +# This must be kept in sync with breathe_projects value in conf.py >> +DOXYGEN_OUTPUT =3D doxygen-output >> + >> +# Doxygen input headers from xen-doxygen/doxy_input.list file >> +DOXY_LIST_SOURCES !=3D cat "xen-doxygen/doxy_input.list" >> +DOXY_LIST_SOURCES :=3D $(realpath $(addprefix $(XEN_ROOT)/,$(DOXY_LIST_= SOURCES))) >> + >> +DOXY_DEPS :=3D xen.doxyfile \ >> + xen-doxygen/mainpage.md \ >> + xen-doxygen/doxygen_include.h >> + >> # Documentation targets >> $(foreach i,$(MAN_SECTIONS), \ >> $(eval DOC_MAN$(i) :=3D $(patsubst man/%.$(i),man$(i)/%.$(i), \ >> @@ -46,8 +58,28 @@ all: build >> build: html txt pdf man-pages figs >>=20 >> .PHONY: sphinx-html >> -sphinx-html: >> - sphinx-build -b html . sphinx/html >> +sphinx-html: $(DOXY_DEPS) $(DOXY_LIST_SOURCES) >> +ifneq ($(SPHINXBUILD),no) >> + $(DOXYGEN) xen.doxyfile >> + XEN_ROOT=3D$(realpath $(XEN_ROOT)) $(SPHINXBUILD) -b html . sphinx/htm= l >> +else >> + @echo "Sphinx is not installed; skipping sphinx-html documentation." >> +endif >> + >> +xen.doxyfile: xen.doxyfile.in xen-doxygen/doxy_input.list >> + @echo "Generating $@" >> + @sed -e "s,@XEN_BASE@,$(realpath $(XEN_ROOT)),g" $< \ >> + | sed -e "s,@DOXY_OUT@,$(DOXYGEN_OUTPUT),g" > $@.tmp >> + @$(foreach inc,\ >> + $(DOXY_LIST_SOURCES),\ >> + echo "INPUT +=3D \"$(inc)\"" >> $@.tmp; \ >> + ) >> + mv $@.tmp $@ >> + >> +xen-doxygen/doxygen_include.h: xen-doxygen/doxygen_include.h.in >> + @echo "Generating $@" >> + @sed -e "s,@XEN_BASE@,$(realpath $(XEN_ROOT)),g" $< > $@.tmp >> + @mv $@.tmp $@ >>=20 >> .PHONY: html >> html: $(DOC_HTML) html/index.html >> @@ -71,7 +103,11 @@ clean: clean-man-pages >> $(MAKE) -C figs clean >> rm -rf .word_count *.aux *.dvi *.bbl *.blg *.glo *.idx *~ >> rm -rf *.ilg *.log *.ind *.toc *.bak *.tmp core >> - rm -rf html txt pdf sphinx/html >> + rm -rf html txt pdf sphinx $(DOXYGEN_OUTPUT) >> + rm -f xen.doxyfile >> + rm -f xen.doxyfile.tmp >> + rm -f xen-doxygen/doxygen_include.h >> + rm -f xen-doxygen/doxygen_include.h.tmp >>=20 >> .PHONY: distclean >> distclean: clean >> diff --git a/docs/conf.py b/docs/conf.py >> index 50e41501db..a48de42331 100644 >> --- a/docs/conf.py >> +++ b/docs/conf.py >> @@ -13,13 +13,17 @@ >> # add these directories to sys.path here. If the directory is relative t= o the >> # documentation root, use os.path.abspath to make it absolute, like show= n here. >> # >> -# import os >> -# import sys >> +import os >> +import sys >> # sys.path.insert(0, os.path.abspath('.')) >>=20 >>=20 >> # -- Project information -----------------------------------------------= ------ >>=20 >> +if "XEN_ROOT" not in os.environ: >> + sys.exit("$XEN_ROOT environment variable undefined.") >> +XEN_ROOT =3D os.path.abspath(os.environ["XEN_ROOT"]) >> + >> project =3D u'Xen' >> copyright =3D u'2019, The Xen development community' >> author =3D u'The Xen development community' >> @@ -35,6 +39,7 @@ try: >> xen_subver =3D line.split(u"=3D")[1].strip() >> elif line.startswith(u"export XEN_EXTRAVERSION"): >> xen_extra =3D line.split(u"=3D")[1].split(u"$", 1)[0].strip(= ) >> + >> except: >> pass >> finally: >> @@ -44,6 +49,15 @@ finally: >> else: >> version =3D release =3D u"unknown version" >>=20 >> +try: >> + xen_doxygen_output =3D None >> + >> + for line in open(u"Makefile"): >> + if line.startswith(u"DOXYGEN_OUTPUT"): >> + xen_doxygen_output =3D line.split(u"=3D")[1].strip() >> +except: >> + sys.exit("DOXYGEN_OUTPUT variable undefined.") >> + >> # -- General configuration ---------------------------------------------= ------ >>=20 >> # If your documentation needs a minimal Sphinx version, state it here. >> @@ -53,7 +67,8 @@ needs_sphinx =3D '1.4' >> # Add any Sphinx extension module names here, as strings. They can be >> # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom >> # ones. >> -extensions =3D [] >> +# breathe -> extension that integrates doxygen xml output with sphinx >> +extensions =3D ['breathe'] >>=20 >> # Add any paths that contain templates here, relative to this directory. >> templates_path =3D ['_templates'] >> @@ -175,6 +190,33 @@ texinfo_documents =3D [ >> 'Miscellaneous'), >> ] >>=20 >> +# -- Options for Breathe extension ------------------------------------= ------- >> + >> +breathe_projects =3D { >> + "Xen": "{}/docs/{}/xml".format(XEN_ROOT, xen_doxygen_output) >> +} >> +breathe_default_project =3D "Xen" >> + >> +breathe_domain_by_extension =3D { >> + "h": "c", >> + "c": "c", >> +} >> +breathe_separate_member_pages =3D True >> +breathe_show_enumvalue_initializer =3D True >> +breathe_show_define_initializer =3D True >> + >> +# Qualifiers to a function are causing Sphihx/Breathe to warn about >> +# Error when parsing function declaration and more. This is a list >> +# of strings that the parser additionally should accept as >> +# attributes. >> +cpp_id_attributes =3D [ >> + '__syscall', '__deprecated', '__may_alias', >> + '__used', '__unused', '__weak', >> + '__DEPRECATED_MACRO', 'FUNC_NORETURN', >> + '__subsystem', >> +] >> +c_id_attributes =3D cpp_id_attributes >> + >>=20 >> # -- Options for Epub output -------------------------------------------= ------ >>=20 >> diff --git a/docs/configure b/docs/configure >> index 569bd4c2ff..0ebf046a79 100755 >> --- a/docs/configure >> +++ b/docs/configure >> @@ -588,6 +588,8 @@ ac_unique_file=3D"misc/xen-command-line.pandoc" >> ac_subst_vars=3D'LTLIBOBJS >> LIBOBJS >> PERL >> +DOXYGEN >> +SPHINXBUILD >> PANDOC >> POD2TEXT >> POD2HTML >> @@ -673,6 +675,7 @@ POD2MAN >> POD2HTML >> POD2TEXT >> PANDOC >> +DOXYGEN >> PERL' >>=20 >>=20 >> @@ -1318,6 +1321,7 @@ Some influential environment variables: >> POD2HTML Path to pod2html tool >> POD2TEXT Path to pod2text tool >> PANDOC Path to pandoc tool >> + DOXYGEN Path to doxygen tool >> PERL Path to Perl parser >>=20 >> Use these variables to override the choices made by `configure' or to he= lp >> @@ -1800,6 +1804,7 @@ ac_configure=3D"$SHELL $ac_aux_dir/configure" # P= lease don't use this var. >>=20 >>=20 >>=20 >> + >> case "$host_os" in >> *freebsd*) XENSTORED_KVA=3D/dev/xen/xenstored ;; >> *) XENSTORED_KVA=3D/proc/xen/xsd_kva ;; >> @@ -1812,6 +1817,53 @@ case "$host_os" in >> esac >>=20 >>=20 >> +# =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D >> +# https://www.gnu.org/software/autoconf-archive/ax_python_module.ht= ml >> +# =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D >> +# >> +# SYNOPSIS >> +# >> +# AX_PYTHON_MODULE(modname[, fatal, python]) >> +# >> +# DESCRIPTION >> +# >> +# Checks for Python module. >> +# >> +# If fatal is non-empty then absence of a module will trigger an erro= r. >> +# The third parameter can either be "python" for Python 2 or "python3= " for >> +# Python 3; defaults to Python 3. >> +# >> +# LICENSE >> +# >> +# Copyright (c) 2008 Andrew Collier >> +# >> +# Copying and distribution of this file, with or without modification= , are >> +# permitted in any medium without royalty provided the copyright noti= ce >> +# and this notice are preserved. This file is offered as-is, without = any >> +# warranty. >> + >> +#serial 9 >> + >> +# This is what autoupdate's m4 run will expand. It fires >> +# the warning (with _au_warn_XXX), outputs it into the >> +# updated configure.ac (with AC_DIAGNOSE), and then outputs >> +# the replacement expansion. >> + >> + >> +# This is an auxiliary macro that is also run when >> +# autoupdate runs m4. It simply calls m4_warning, but >> +# we need a wrapper so that each warning is emitted only >> +# once. We break the quoting in m4_warning's argument in >> +# order to expand this macro's arguments, not AU_DEFUN's. >> + >> + >> +# Finally, this is the expansion that is picked up by >> +# autoconf. It tells the user to run autoupdate, and >> +# then outputs the replacement expansion. We do not care >> +# about autoupdate's warning because that contains >> +# information on what to do *after* running autoupdate. >> + >> + >>=20 >>=20 >> test "x$prefix" =3D "xNONE" && prefix=3D$ac_default_prefix >> @@ -2232,6 +2284,212 @@ $as_echo "$as_me: WARNING: pandoc is not availab= le so some documentation won't b >> fi >>=20 >>=20 >> +# If sphinx is installed, make sure to have also the dependencies to bu= ild >> +# Sphinx documentation. >> +for ac_prog in sphinx-build >> +do >> + # Extract the first word of "$ac_prog", so it can be a program name w= ith args. >> +set dummy $ac_prog; ac_word=3D$2 >> +{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 >> +$as_echo_n "checking for $ac_word... " >&6; } >> +if ${ac_cv_prog_SPHINXBUILD+:} false; then : >> + $as_echo_n "(cached) " >&6 >> +else >> + if test -n "$SPHINXBUILD"; then >> + ac_cv_prog_SPHINXBUILD=3D"$SPHINXBUILD" # Let the user override the t= est. >> +else >> +as_save_IFS=3D$IFS; IFS=3D$PATH_SEPARATOR >> +for as_dir in $PATH >> +do >> + IFS=3D$as_save_IFS >> + test -z "$as_dir" && as_dir=3D. >> + for ac_exec_ext in '' $ac_executable_extensions; do >> + if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then >> + ac_cv_prog_SPHINXBUILD=3D"$ac_prog" >> + $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_ex= ec_ext" >&5 >> + break 2 >> + fi >> +done >> + done >> +IFS=3D$as_save_IFS >> + >> +fi >> +fi >> +SPHINXBUILD=3D$ac_cv_prog_SPHINXBUILD >> +if test -n "$SPHINXBUILD"; then >> + { $as_echo "$as_me:${as_lineno-$LINENO}: result: $SPHINXBUILD" >&5 >> +$as_echo "$SPHINXBUILD" >&6; } >> +else >> + { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 >> +$as_echo "no" >&6; } >> +fi >> + >> + >> + test -n "$SPHINXBUILD" && break >> +done >> +test -n "$SPHINXBUILD" || SPHINXBUILD=3D"no" >> + >> + if test "x$SPHINXBUILD" =3D xno; then : >> + { $as_echo "$as_me:${as_lineno-$LINENO}: WARNING: sphinx-build is not= available so sphinx documentation \ >> +won't be built" >&5 >> +$as_echo "$as_me: WARNING: sphinx-build is not available so sphinx docu= mentation \ >> +won't be built" >&2;} >> +else >> + >> + # Extract the first word of "sphinx-build", so it can be a = program name with args. >> +set dummy sphinx-build; ac_word=3D$2 >> +{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 >> +$as_echo_n "checking for $ac_word... " >&6; } >> +if ${ac_cv_path_SPHINXBUILD+:} false; then : >> + $as_echo_n "(cached) " >&6 >> +else >> + case $SPHINXBUILD in >> + [\\/]* | ?:[\\/]*) >> + ac_cv_path_SPHINXBUILD=3D"$SPHINXBUILD" # Let the user override the t= est with a path. >> + ;; >> + *) >> + as_save_IFS=3D$IFS; IFS=3D$PATH_SEPARATOR >> +for as_dir in $PATH >> +do >> + IFS=3D$as_save_IFS >> + test -z "$as_dir" && as_dir=3D. >> + for ac_exec_ext in '' $ac_executable_extensions; do >> + if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then >> + ac_cv_path_SPHINXBUILD=3D"$as_dir/$ac_word$ac_exec_ext" >> + $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_ex= ec_ext" >&5 >> + break 2 >> + fi >> +done >> + done >> +IFS=3D$as_save_IFS >> + >> + ;; >> +esac >> +fi >> +SPHINXBUILD=3D$ac_cv_path_SPHINXBUILD >> +if test -n "$SPHINXBUILD"; then >> + { $as_echo "$as_me:${as_lineno-$LINENO}: result: $SPHINXBUILD" >&5 >> +$as_echo "$SPHINXBUILD" >&6; } >> +else >> + { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 >> +$as_echo "no" >&6; } >> +fi >> + >> + >> + >> + >> + # Extract the first word of "doxygen", so it can be a program name = with args. >> +set dummy doxygen; ac_word=3D$2 >> +{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5 >> +$as_echo_n "checking for $ac_word... " >&6; } >> +if ${ac_cv_path_DOXYGEN+:} false; then : >> + $as_echo_n "(cached) " >&6 >> +else >> + case $DOXYGEN in >> + [\\/]* | ?:[\\/]*) >> + ac_cv_path_DOXYGEN=3D"$DOXYGEN" # Let the user override the test with= a path. >> + ;; >> + *) >> + as_save_IFS=3D$IFS; IFS=3D$PATH_SEPARATOR >> +for as_dir in $PATH >> +do >> + IFS=3D$as_save_IFS >> + test -z "$as_dir" && as_dir=3D. >> + for ac_exec_ext in '' $ac_executable_extensions; do >> + if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then >> + ac_cv_path_DOXYGEN=3D"$as_dir/$ac_word$ac_exec_ext" >> + $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_ex= ec_ext" >&5 >> + break 2 >> + fi >> +done >> + done >> +IFS=3D$as_save_IFS >> + >> + ;; >> +esac >> +fi >> +DOXYGEN=3D$ac_cv_path_DOXYGEN >> +if test -n "$DOXYGEN"; then >> + { $as_echo "$as_me:${as_lineno-$LINENO}: result: $DOXYGEN" >&5 >> +$as_echo "$DOXYGEN" >&6; } >> +else >> + { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 >> +$as_echo "no" >&6; } >> +fi >> + >> + >> + if ! test -x "$ac_cv_path_DOXYGEN"; then : >> + >> + as_fn_error $? "doxygen is needed" "$LINENO" 5 >> + >> +fi >> + >> + >> + if test -z $PYTHON; >> + then >> + if test -z ""; >> + then >> + PYTHON=3D"python3" >> + else >> + PYTHON=3D"" >> + fi >> + fi >> + PYTHON_NAME=3D`basename $PYTHON` >> + { $as_echo "$as_me:${as_lineno-$LINENO}: checking $PYTHON_NAME modu= le: breathe" >&5 >> +$as_echo_n "checking $PYTHON_NAME module: breathe... " >&6; } >> + $PYTHON -c "import breathe" 2>/dev/null >> + if test $? -eq 0; >> + then >> + { $as_echo "$as_me:${as_lineno-$LINENO}: result: yes" >&5 >> +$as_echo "yes" >&6; } >> + eval HAVE_PYMOD_BREATHE=3Dyes >> + else >> + { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 >> +$as_echo "no" >&6; } >> + eval HAVE_PYMOD_BREATHE=3Dno >> + # >> + if test -n "yes" >> + then >> + as_fn_error $? "failed to find required module breathe" "$L= INENO" 5 >> + exit 1 >> + fi >> + fi >> + >> + >> + if test -z $PYTHON; >> + then >> + if test -z ""; >> + then >> + PYTHON=3D"python3" >> + else >> + PYTHON=3D"" >> + fi >> + fi >> + PYTHON_NAME=3D`basename $PYTHON` >> + { $as_echo "$as_me:${as_lineno-$LINENO}: checking $PYTHON_NAME modu= le: sphinx_rtd_theme" >&5 >> +$as_echo_n "checking $PYTHON_NAME module: sphinx_rtd_theme... " >&6; } >> + $PYTHON -c "import sphinx_rtd_theme" 2>/dev/null >> + if test $? -eq 0; >> + then >> + { $as_echo "$as_me:${as_lineno-$LINENO}: result: yes" >&5 >> +$as_echo "yes" >&6; } >> + eval HAVE_PYMOD_SPHINX_RTD_THEME=3Dyes >> + else >> + { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5 >> +$as_echo "no" >&6; } >> + eval HAVE_PYMOD_SPHINX_RTD_THEME=3Dno >> + # >> + if test -n "yes" >> + then >> + as_fn_error $? "failed to find required module sphinx_rtd_t= heme" "$LINENO" 5 >> + exit 1 >> + fi >> + fi >> + >> + >> + >> +fi >> + >>=20 >> # Extract the first word of "perl", so it can be a program name with arg= s. >> set dummy perl; ac_word=3D$2 >> diff --git a/docs/configure.ac b/docs/configure.ac >> index c2e5edd3b3..a2ff55f30a 100644 >> --- a/docs/configure.ac >> +++ b/docs/configure.ac >> @@ -20,6 +20,7 @@ m4_include([../m4/docs_tool.m4]) >> m4_include([../m4/path_or_fail.m4]) >> m4_include([../m4/features.m4]) >> m4_include([../m4/paths.m4]) >> +m4_include([../m4/ax_python_module.m4]) >>=20 >> AX_XEN_EXPAND_CONFIG() >>=20 >> @@ -29,6 +30,20 @@ AX_DOCS_TOOL_PROG([POD2HTML], [pod2html]) >> AX_DOCS_TOOL_PROG([POD2TEXT], [pod2text]) >> AX_DOCS_TOOL_PROG([PANDOC], [pandoc]) >>=20 >> +# If sphinx is installed, make sure to have also the dependencies to bu= ild >> +# Sphinx documentation. >> +AC_CHECK_PROGS([SPHINXBUILD], [sphinx-build], [no]) >> + AS_IF([test "x$SPHINXBUILD" =3D xno], >> + [AC_MSG_WARN(sphinx-build is not available so sphinx documentat= ion \ >> +won't be built)], >> + [ >> + AC_PATH_PROG([SPHINXBUILD], [sphinx-build]) >> + AX_DOCS_TOOL_REQ_PROG([DOXYGEN], [doxygen]) >> + AX_PYTHON_MODULE([breathe],[yes]) >> + AX_PYTHON_MODULE([sphinx_rtd_theme], [yes]) >> + ] >> + ) >> + >> AC_ARG_VAR([PERL], [Path to Perl parser]) >> AX_PATH_PROG_OR_FAIL([PERL], [perl]) >>=20 >> diff --git a/docs/xen-doxygen/customdoxygen.css b/docs/xen-doxygen/custo= mdoxygen.css >> new file mode 100644 >> index 0000000000..4735e41cf5 >> --- /dev/null >> +++ b/docs/xen-doxygen/customdoxygen.css >> @@ -0,0 +1,36 @@ >> +/* Custom CSS for Doxygen-generated HTML >> + * Copyright (c) 2015 Intel Corporation >> + * SPDX-License-Identifier: Apache-2.0 >> + */ >> + >> +code { >> + font-family: Monaco,Menlo,Consolas,"Courier New",monospace; >> + background-color: #D8D8D8; >> + padding: 0 0.25em 0 0.25em; >> +} >> + >> +pre.fragment { >> + display: block; >> + font-family: Monaco,Menlo,Consolas,"Courier New",monospace; >> + padding: 1rem; >> + word-break: break-all; >> + word-wrap: break-word; >> + white-space: pre; >> + background-color: #D8D8D8; >> +} >> + >> +#projectlogo >> +{ >> + vertical-align: middle; >> +} >> + >> +#projectname >> +{ >> + font: 200% Tahoma, Arial,sans-serif; >> + color: #3D578C; >> +} >> + >> +#projectbrief >> +{ >> + color: #3D578C; >> +} >> diff --git a/docs/xen-doxygen/doxy-preprocessor.py b/docs/xen-doxygen/do= xy-preprocessor.py >> new file mode 100755 >> index 0000000000..496899d8e6 >> --- /dev/null >> +++ b/docs/xen-doxygen/doxy-preprocessor.py >> @@ -0,0 +1,110 @@ >> +#!/usr/bin/python3 >> +# >> +# Copyright (c) 2021, Arm Limited. >> +# >> +# SPDX-License-Identifier: GPL-2.0 >> +# >> + >> +import os, sys, re >> + >> + >> +# Variables that holds the preprocessed header text >> +output_text =3D "" >> +header_file_name =3D "" >> + >> +# Variables to enumerate the anonymous structs/unions >> +anonymous_struct_count =3D 0 >> +anonymous_union_count =3D 0 >> + >> + >> +def error(text): >> + sys.stderr.write("{}\n".format(text)) >> + sys.exit(1) >> + >> + >> +def write_to_output(text): >> + sys.stdout.write(text) >> + >> + >> +def insert_doxygen_header(text): >> + # Here the strategy is to insert the #include i= n the >> + # first line of the header >> + abspath =3D os.path.dirname(os.path.abspath(__file__)) >> + text +=3D "#include \"{}/doxygen_include.h\"\n".format(abspath) >> + >> + return text >> + >> + >> +def enumerate_anonymous(match): >> + global anonymous_struct_count >> + global anonymous_union_count >> + >> + if "struct" in match.group(1): >> + label =3D "anonymous_struct_%d" % anonymous_struct_count >> + anonymous_struct_count +=3D 1 >> + else: >> + label =3D "anonymous_union_%d" % anonymous_union_count >> + anonymous_union_count +=3D 1 >> + >> + return match.group(1) + " " + label + " {" >> + >> + >> +def manage_anonymous_structs_unions(text): >> + # Match anonymous unions/structs with this pattern: >> + # struct/union { >> + # [...] >> + # >> + # and substitute it in this way: >> + # >> + # struct anonymous_struct_# { >> + # [...] >> + # or >> + # union anonymous_union_# { >> + # [...] >> + # where # is a counter starting from zero, different between struct= s and >> + # unions >> + # >> + # We don't count anonymous union/struct that are part of a typedef = because >> + # they don't create any issue for doxygen >> + text =3D re.sub( >> + "(?> + enumerate_anonymous, >> + text, >> + flags=3Dre.S >> + ) >> + >> + return text >> + >> + >> +def main(argv): >> + global output_text >> + global header_file_name >> + >> + if len(argv) !=3D 1: >> + error("Script called without arguments!") >> + >> + header_file_name =3D argv[0] >> + >> + # Open header file >> + input_header_file =3D open(header_file_name, 'r') >> + # Read all lines >> + lines =3D input_header_file.readlines() >> + >> + # Inject config.h and some defines in the current header, during co= mpilation >> + # this job is done by the -include argument passed to the compiler. >> + output_text =3D insert_doxygen_header(output_text) >> + >> + # Load file content in a variable >> + for line in lines: >> + output_text +=3D "{}".format(line) >> + >> + # Try to get rid of any anonymous union/struct >> + output_text =3D manage_anonymous_structs_unions(output_text) >> + >> + # Final stage of the preprocessor, print the output to stdout >> + write_to_output(output_text) >> + >> + >> +if __name__ =3D=3D "__main__": >> + main(sys.argv[1:]) >> + sys.exit(0) >> diff --git a/docs/xen-doxygen/doxy_input.list b/docs/xen-doxygen/doxy_in= put.list >> new file mode 100644 >> index 0000000000..e69de29bb2 >> diff --git a/docs/xen-doxygen/doxygen_include.h.in b/docs/xen-doxygen/do= xygen_include.h.in >> new file mode 100644 >> index 0000000000..df284f3931 >> --- /dev/null >> +++ b/docs/xen-doxygen/doxygen_include.h.in >> @@ -0,0 +1,32 @@ >> +/* >> + * Doxygen include header >> + * It supplies the xen/include/xen/config.h that is included using the = -include >> + * argument of the compiler in Xen Makefile. >> + * Other macros are defined because they are usually provided by the co= mpiler. >> + * >> + * Copyright (C) 2021 ARM Limited >> + * >> + * Author: Luca Fancellu >> + * >> + * SPDX-License-Identifier: GPL-2.0 >> + */ >> + >> +#include "@XEN_BASE@/xen/include/xen/config.h" >> + >> +#if defined(CONFIG_X86_64) >> + >> +#define __x86_64__ 1 >> + >> +#elif defined(CONFIG_ARM_64) >> + >> +#define __aarch64__ 1 >> + >> +#elif defined(CONFIG_ARM_32) >> + >> +#define __arm__ 1 >> + >> +#else >> + >> +#error Architecture not supported/recognized. >> + >> +#endif >> diff --git a/docs/xen-doxygen/footer.html b/docs/xen-doxygen/footer.html >> new file mode 100644 >> index 0000000000..a24bf2b9b4 >> --- /dev/null >> +++ b/docs/xen-doxygen/footer.html >> @@ -0,0 +1,21 @@ >> + >> + >> + >> +
>> +
    >> + $navpath >> +
  • $generatedby >> + >> + 3D"doxygen"/= $doxygenversion
    • >> +
>> +
>> + >> + >> +
>> +$generatedby   >> +3D"doxygen"/ >> + $doxygenversion >> +
>> + >> + >> + >> diff --git a/docs/xen-doxygen/header.html b/docs/xen-doxygen/header.html >> new file mode 100644 >> index 0000000000..83ac2f1835 >> --- /dev/null >> +++ b/docs/xen-doxygen/header.html >> @@ -0,0 +1,56 @@ >> + >> + >> + >> + >> + >> + >> + >> + >> +$projectname: $title >> +$title >> + >> + >> +