[{"id":2814614,"web_url":"http://patchwork.ozlabs.org/comment/2814614/","msgid":"","list_archive_url":null,"date":"2022-01-03T20:52:14","subject":"Re: [PULL v2 20/36] docs/sphinx: add sphinx modules to include D-Bus\n documentation","submitter":{"id":66152,"url":"http://patchwork.ozlabs.org/api/people/66152/","name":"Thomas Huth","email":"thuth@redhat.com"},"content":"On 21/12/2021 07.58, marcandre.lureau@redhat.com wrote:\n> From: Marc-André Lureau \n> \n> Add a new dbus-doc directive to import D-Bus interfaces documentation\n> from the introspection XML. The comments annotations follow the\n> gtkdoc/kerneldoc style, and should be formatted with reST.\n> \n> Note: I realize after the fact that I was implementing those modules\n> with sphinx 4, and that we have much lower requirements. Instead of\n> lowering the features and code (removing type annotations etc), let's\n> have a warning in the documentation when the D-Bus modules can't be\n> used, and point to the source XML file in that case.\n> \n> Signed-off-by: Marc-André Lureau \n> Acked-by: Gerd Hoffmann \n> ---\n> docs/conf.py | 8 +\n> docs/sphinx/dbusdoc.py | 166 +++++++++++++++\n> docs/sphinx/dbusdomain.py | 406 +++++++++++++++++++++++++++++++++++++\n> docs/sphinx/dbusparser.py | 373 ++++++++++++++++++++++++++++++++++\n> docs/sphinx/fakedbusdoc.py | 25 +++\n> 5 files changed, 978 insertions(+)\n> create mode 100644 docs/sphinx/dbusdoc.py\n> create mode 100644 docs/sphinx/dbusdomain.py\n> create mode 100644 docs/sphinx/dbusparser.py\n> create mode 100644 docs/sphinx/fakedbusdoc.py\n> \n> diff --git a/docs/conf.py b/docs/conf.py\n> index 763e7d243448..e79015975e6a 100644\n> --- a/docs/conf.py\n> +++ b/docs/conf.py\n> @@ -73,6 +73,12 @@\n> # ones.\n> extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile', 'qapidoc']\n> \n> +if sphinx.version_info[:3] > (4, 0, 0):\n> + tags.add('sphinx4')\n> + extensions += ['dbusdoc']\n> +else:\n> + extensions += ['fakedbusdoc']\n> +\n> # Add any paths that contain templates here, relative to this directory.\n> templates_path = [os.path.join(qemu_docdir, '_templates')]\n> \n> @@ -311,3 +317,5 @@\n> kerneldoc_srctree = os.path.join(qemu_docdir, '..')\n> hxtool_srctree = os.path.join(qemu_docdir, '..')\n> qapidoc_srctree = os.path.join(qemu_docdir, '..')\n> +dbusdoc_srctree = os.path.join(qemu_docdir, '..')\n> +dbus_index_common_prefix = [\"org.qemu.\"]\n\nThis does not work with my version of Sphinx (v 1.7.6):\n\nProgram sphinx-build-3 found: YES (/usr/bin/sphinx-build-3)\n../../home/thuth/devel/qemu/docs/meson.build:30: WARNING: \n/usr/bin/sphinx-build-3:\nExtension error:\nCould not import extension fakedbusdoc (exception: cannot import name \n'SphinxDirective')\n\nAny ideas how to fix it?\n\n Thomas","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@bilbo.ozlabs.org","Authentication-Results":["bilbo.ozlabs.org;\n\tdkim=pass (1024-bit key;\n unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256\n header.s=mimecast20190719 header.b=YEu9qnqC;\n\tdkim-atps=neutral","ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org\n (client-ip=209.51.188.17; helo=lists.gnu.org;\n envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n receiver=)","relay.mimecast.com;\n auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=thuth@redhat.com"],"Received":["from lists.gnu.org (lists.gnu.org [209.51.188.17])\n\t(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))\n\t(No client certificate requested)\n\tby bilbo.ozlabs.org (Postfix) with ESMTPS id 4JSScf3ll7z9sRR\n\tfor ; Tue, 4 Jan 2022 07:52:48 +1100 (AEDT)","from localhost ([::1]:36514 helo=lists1p.gnu.org)\n\tby lists.gnu.org with esmtp (Exim 4.90_1)\n\t(envelope-from )\n\tid 1n4UJw-0003yC-7R\n\tfor incoming@patchwork.ozlabs.org; Mon, 03 Jan 2022 15:52:44 -0500","from eggs.gnu.org ([209.51.188.92]:46916)\n by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from ) id 1n4UJc-0003xa-M3\n for qemu-devel@nongnu.org; Mon, 03 Jan 2022 15:52:24 -0500","from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:35240)\n by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from ) id 1n4UJY-0001xv-8B\n for qemu-devel@nongnu.org; Mon, 03 Jan 2022 15:52:23 -0500","from mail-wr1-f72.google.com (mail-wr1-f72.google.com\n [209.85.221.72]) by relay.mimecast.com with ESMTP with STARTTLS\n (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id\n us-mta-202-9vTUfndbPyKu97sChjt7bA-1; Mon, 03 Jan 2022 15:52:17 -0500","by mail-wr1-f72.google.com with SMTP id\n w25-20020adf8bd9000000b001a255212b7cso10663769wra.18\n for ; Mon, 03 Jan 2022 12:52:17 -0800 (PST)","from [192.168.8.100] (tmo-098-68.customers.d1-online.com.\n [80.187.98.68])\n by smtp.gmail.com with ESMTPSA id c13sm35040262wrt.114.2022.01.03.12.52.15\n (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128);\n Mon, 03 Jan 2022 12:52:15 -0800 (PST)"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com;\n s=mimecast20190719; t=1641243138;\n h=from:from:reply-to:subject:subject:date:date:message-id:message-id:\n to:to:cc:cc:mime-version:mime-version:content-type:content-type:\n content-transfer-encoding:content-transfer-encoding:\n in-reply-to:in-reply-to:references:references;\n bh=ABU3XNj2HJ7n7M9kme8C3z7FRWvYadGdaNCEPuF0wM8=;\n b=YEu9qnqCHQoY1wwe9btXBBYCgXmHB6qdmRc2lQCwhuMzNxkD5q1MtC6rI4SQN//nLQ6t3N\n 9LsXA7lYsnmHLIWmaaINe4VpXjbw2Lbm0eWQxYYEcvc/ocAiEylzeSCREebEIvvDo7M4uY\n E92g9DGyyzfam6JNlu7wOiEbT3TknUI=","X-MC-Unique":"9vTUfndbPyKu97sChjt7bA-1","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20210112;\n h=x-gm-message-state:message-id:date:mime-version:user-agent:subject\n :content-language:to:cc:references:from:in-reply-to\n :content-transfer-encoding;\n bh=ABU3XNj2HJ7n7M9kme8C3z7FRWvYadGdaNCEPuF0wM8=;\n b=LF+SMIULXVDvF+CnpVDVrx6kN1nHz7b5Bc9FrerI01zCfaql5axuEibW9Mfx0al/HL\n KGxJdY0sTvBMjVsE6th/Z2n1mqIK+mbjnK4vjC/skhd+ixnpvUP0GQOOfnauZKqWfYCQ\n jzaGVuX4I86Z6oz9pFs/hbOtyIyXRXlnKvTtwbu1PF0eaeQNVS8GRr2NK+6ULBu9rI5X\n bdi2FJeHlXQCwLh5r9owcgT696dkQdxHQuRc9W+eLtet4Yoa5knhWw9o2KBz0qIyUoJd\n HYO3X8bqcUbG92pcsuZLE2CDk5aMNUb0ci5NA0ypfsAuqHZ7H0mHBrFL41xb6+lIAqKE\n EMdg==","X-Gm-Message-State":"AOAM531g2pEOemW75mfpw+/xWUr9vRjt7WV/sK8ffH0MuLXMYfEZjb6w\n G7QBeV3zLu6zfM6fG8e4tZS0BND5HLFyvip6b0khtHPgJV19BHh7dH2ILT7JC1A670KL4Gpc8By\n 1bzZ2/Gy37fu/jc4=","X-Received":["by 2002:a05:6000:124a:: with SMTP id\n j10mr39181612wrx.110.1641243136509;\n Mon, 03 Jan 2022 12:52:16 -0800 (PST)","by 2002:a05:6000:124a:: with SMTP id\n j10mr39181598wrx.110.1641243136312;\n Mon, 03 Jan 2022 12:52:16 -0800 (PST)"],"X-Google-Smtp-Source":"\n ABdhPJziA/OILY4en/D6/Bj9e6A2hrbVBEtHW2n7oKR0+Jg/T62ae0WoTn7QB020jQIOW/44OTKD8g==","Message-ID":"","Date":"Mon, 3 Jan 2022 21:52:14 +0100","MIME-Version":"1.0","User-Agent":"Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101\n Thunderbird/91.4.0","Subject":"Re: [PULL v2 20/36] docs/sphinx: add sphinx modules to include D-Bus\n documentation","To":"marcandre.lureau@redhat.com, qemu-devel@nongnu.org","References":"<20211221065855.142578-1-marcandre.lureau@redhat.com>\n <20211221065855.142578-21-marcandre.lureau@redhat.com>","From":"Thomas Huth ","In-Reply-To":"<20211221065855.142578-21-marcandre.lureau@redhat.com>","X-Mimecast-Spam-Score":"0","X-Mimecast-Originator":"redhat.com","Content-Language":"en-US","Content-Type":"text/plain; charset=UTF-8; format=flowed","Content-Transfer-Encoding":"8bit","Received-SPF":"pass client-ip=170.10.133.124; envelope-from=thuth@redhat.com;\n helo=us-smtp-delivery-124.mimecast.com","X-Spam_score_int":"-45","X-Spam_score":"-4.6","X-Spam_bar":"----","X-Spam_report":"(-4.6 / 5.0 requ) DKIMWL_WL_HIGH=-0.37, DKIM_SIGNED=0.1,\n DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, NICE_REPLY_A=-3.354,\n RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001,\n SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no","X-Spam_action":"no action","X-BeenThere":"qemu-devel@nongnu.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n ","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n ","Cc":"peter.maydell@linaro.org, richard.henderson@linaro.org","Errors-To":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org","Sender":"\"Qemu-devel\"\n "}}]