Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/91945/?format=api
{ "id": 91945, "url": "https://patches.dpdk.org/api/patches/91945/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/patch/20210421091146.1384708-1-conor.walsh@intel.com/", "project": { "id": 1, "url": "https://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<20210421091146.1384708-1-conor.walsh@intel.com>", "list_archive_url": "https://inbox.dpdk.org/dev/20210421091146.1384708-1-conor.walsh@intel.com", "date": "2021-04-21T09:11:46", "name": "doc/contributing/documentation: add info about including code", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "17c37edc781b115783a948c3c72ac97b5e2a19ba", "submitter": { "id": 1935, "url": "https://patches.dpdk.org/api/people/1935/?format=api", "name": "Conor Walsh", "email": "conor.walsh@intel.com" }, "delegate": { "id": 1, "url": "https://patches.dpdk.org/api/users/1/?format=api", "username": "tmonjalo", "first_name": "Thomas", "last_name": "Monjalon", "email": "thomas@monjalon.net" }, "mbox": "https://patches.dpdk.org/project/dpdk/patch/20210421091146.1384708-1-conor.walsh@intel.com/mbox/", "series": [ { "id": 16558, "url": "https://patches.dpdk.org/api/series/16558/?format=api", "web_url": "https://patches.dpdk.org/project/dpdk/list/?series=16558", "date": "2021-04-21T09:11:46", "name": "doc/contributing/documentation: add info about including code", "version": 1, "mbox": "https://patches.dpdk.org/series/16558/mbox/" } ], "comments": "https://patches.dpdk.org/api/patches/91945/comments/", "check": "warning", "checks": "https://patches.dpdk.org/api/patches/91945/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@inbox.dpdk.org", "Delivered-To": "patchwork@inbox.dpdk.org", "Received": [ "from mails.dpdk.org (mails.dpdk.org [217.70.189.124])\n\tby inbox.dpdk.org (Postfix) with ESMTP id 10252A0548;\n\tWed, 21 Apr 2021 11:12:06 +0200 (CEST)", "from [217.70.189.124] (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 8FB5E419EC;\n\tWed, 21 Apr 2021 11:12:05 +0200 (CEST)", "from mga14.intel.com (mga14.intel.com [192.55.52.115])\n by mails.dpdk.org (Postfix) with ESMTP id 083BD419D3\n for <dev@dpdk.org>; Wed, 21 Apr 2021 11:12:03 +0200 (CEST)", "from orsmga007.jf.intel.com ([10.7.209.58])\n by fmsmga103.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;\n 21 Apr 2021 02:12:03 -0700", "from silpixa00400466.ir.intel.com ([10.237.213.210])\n by orsmga007.jf.intel.com with ESMTP; 21 Apr 2021 02:12:00 -0700" ], "IronPort-SDR": [ "\n h/wBA8KDj7JVfQI+cqXkpkilza5kOzgKRzKpyo5lP1R3JwVGJPLyr5r6EAqwzpxSx0zIFO3jlG\n QSV3ToQhP0Kw==", "\n MzAH4ncdwX6pEpV+uzbxi+W4G+D7qZnbaMQ7Al9UW2GzrslCFZ2u2I5PmudhsqpUkh/5jEKn/t\n HYcLPdTcBPWg==" ], "X-IronPort-AV": [ "E=McAfee;i=\"6200,9189,9960\"; a=\"195222731\"", "E=Sophos;i=\"5.82,238,1613462400\"; d=\"scan'208\";a=\"195222731\"", "E=Sophos;i=\"5.82,238,1613462400\"; d=\"scan'208\";a=\"423481714\"" ], "X-ExtLoop1": "1", "From": "Conor Walsh <conor.walsh@intel.com>", "To": "john.mcnamara@intel.com, thomas@monjalon.net, david.marchand@redhat.com,\n ferruh.yigit@intel.com, bruce.richardson@intel.com,\n anatoly.burakov@intel.com", "Cc": "dev@dpdk.org,\n\tConor Walsh <conor.walsh@intel.com>", "Date": "Wed, 21 Apr 2021 09:11:46 +0000", "Message-Id": "<20210421091146.1384708-1-conor.walsh@intel.com>", "X-Mailer": "git-send-email 2.25.1", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "Subject": "[dpdk-dev] [PATCH] doc/contributing/documentation: add info about\n including code", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://mails.dpdk.org/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org", "Sender": "\"dev\" <dev-bounces@dpdk.org>" }, "content": "Currently the documentation describes how to add code snippets to the\ndocs using code blocks. This can be problematic as the code snippets\nin the docs may fall out of sync with the actual code it is referencing\nwithin DPDK. This patch adds instructions to the contribution guide\nabout how to include code in the docs using literalinclude which will\ndynamically get the code from source when the docs are generated. This\nwill help to ensure that the code within the docs is up to date and not\nout of sync with the actual code.\n\nSigned-off-by: Conor Walsh <conor.walsh@intel.com>\n---\n doc/guides/contributing/documentation.rst | 45 +++++++++++++++++++++++\n 1 file changed, 45 insertions(+)", "diff": "diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst\nindex a4e6be6aca..d5dd119a9a 100644\n--- a/doc/guides/contributing/documentation.rst\n+++ b/doc/guides/contributing/documentation.rst\n@@ -433,6 +433,51 @@ Code and Literal block sections\n return 0;\n }\n \n+* Code snippets can also be included directly from the code using the ``literalinclude`` block.\n+ Using this block instead of a code block will ensure that the code snippets shown in the\n+ documentation are always up to date with the code.\n+\n+ The following will include a snippet from the skeleton sample app::\n+\n+ .. literalinclude:: ../../../examples/skeleton/basicfwd.c\n+ :language: c\n+ :start-after: Display the port MAC address.\n+ :end-before: Enable RX in promiscuous mode for the Ethernet device.\n+ :dedent: 1\n+\n+ This would be rendered as:\n+\n+ .. literalinclude:: ../../../examples/skeleton/basicfwd.c\n+ :language: c\n+ :start-after: Display the port MAC address.\n+ :end-before: Enable RX in promiscuous mode for the Ethernet device.\n+ :dedent: 1\n+\n+ Specifying ``:language:`` will enable syntax highlighting for the specified language.\n+ ``:dedent:`` is used in this example to remove 1 leading tab from each line of the snippet.\n+\n+* ``start-after`` and ``end-before`` can use any text within a given file,\n+ however it may be difficult to find unique text within your code to mark the\n+ start and end of your snippets. In these cases, it is recommended to include\n+ explicit tags in your code to denote these locations for documentation purposes.\n+\n+ This can be done as follows:\n+\n+ .. code-block:: c\n+\n+ /* #guide_doc: Example feature being documented. */\n+ ...\n+ /* #guide_doc: End of example feature being documented. */\n+\n+ ``...`` could then be included in the docs using::\n+\n+ .. literalinclude:: ../../../examples/sample_app/main.c\n+ :language: c\n+ :start-after: #guide_doc: Example feature being documented.\n+ :end-before: #guide_doc: End of example feature being documented.\n+\n+* More information about the ``literalinclude`` block can be found within the\n+ `Sphinx Documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html?highlight=literalinclude#directive-literalinclude>`_.\n \n * The default encoding for a literal block using the simplified ``::``\n directive is ``none``.\n", "prefixes": [] }