From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 89159A034F; Fri, 7 May 2021 11:54:37 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 0B27D4013F; Fri, 7 May 2021 11:54:37 +0200 (CEST) Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) by mails.dpdk.org (Postfix) with ESMTP id 5E46640040 for ; Fri, 7 May 2021 11:54:34 +0200 (CEST) IronPort-SDR: iRnxiHjklxUSWMOiSyeID+aappwu20iDkHG5bYU+txQqSoTCHfnFjjGPF5O/Bj35FOv3fVb8EP 8NOxl4TXziUw== X-IronPort-AV: E=McAfee;i="6200,9189,9976"; a="196677148" X-IronPort-AV: E=Sophos;i="5.82,280,1613462400"; d="scan'208";a="196677148" Received: from orsmga008.jf.intel.com ([10.7.209.65]) by fmsmga104.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 07 May 2021 02:54:33 -0700 IronPort-SDR: WqvZhkGzOnjfWcQpdFnYw72R3d8Zced0D1KiPGyWtg93sRB96fNiFSNsOsBMuo44jBCBwl+vEy mYjy+miDsFxg== X-IronPort-AV: E=Sophos;i="5.82,280,1613462400"; d="scan'208";a="434840910" Received: from aburakov-mobl.ger.corp.intel.com (HELO [10.213.245.37]) ([10.213.245.37]) by orsmga008-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 07 May 2021 02:54:31 -0700 To: Conor Walsh , john.mcnamara@intel.com, thomas@monjalon.net, david.marchand@redhat.com, ferruh.yigit@intel.com, bruce.richardson@intel.com Cc: dev@dpdk.org, conor.fogarty@intel.com References: <20210421091146.1384708-1-conor.walsh@intel.com> <20210506164059.694490-1-conor.walsh@intel.com> From: "Burakov, Anatoly" Message-ID: <86c40b7f-1035-c8ab-f10a-bb9b3146249b@intel.com> Date: Fri, 7 May 2021 10:54:29 +0100 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Thunderbird/78.10.1 MIME-Version: 1.0 In-Reply-To: <20210506164059.694490-1-conor.walsh@intel.com> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit Subject: Re: [dpdk-dev] [PATCH v2] doc/contributing/doc: add info about including code X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" On 06-May-21 5:40 PM, Conor Walsh wrote: > Currently the documentation describes how to add code snippets to the > docs using code blocks. This can be problematic as the code snippets > in the docs may fall out of sync with the actual code it is referencing > within DPDK. This patch adds instructions to the contribution guide > about how to include code in the docs using literalinclude which will > dynamically get the code from source when the docs are generated. This > will help to ensure that the code within the docs is up to date and not > out of sync with the actual code. > Note: literalinclude was used in the past and was removed from DPDK as > it created an issue with PDF generation but this is not done anymore: > git.dpdk.org/dpdk/commit/?id=d3ce1dc637c1bbef9a407f10281b2bc0549256da > > Signed-off-by: Conor Walsh > Acked-by: John McNamara > Acked-by: David Marchand > > --- > > v2: indentation changes and moved to scissor syntax > --- > doc/guides/contributing/documentation.rst | 56 +++++++++++++++++++++++ > 1 file changed, 56 insertions(+) > > diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst > index a4e6be6aca..7a0df1dc47 100644 > --- a/doc/guides/contributing/documentation.rst > +++ b/doc/guides/contributing/documentation.rst > @@ -433,6 +433,62 @@ Code and Literal block sections > return 0; > } > > +* Code snippets can also be included directly from the code using the ``literalinclude`` block. > + Using this block instead of a code block will ensure that the code snippets shown in the > + documentation are always up to date with the code. > + > + The following will include a snippet from the skeleton sample app:: > + > + .. literalinclude:: ../../../examples/skeleton/basicfwd.c > + :language: c > + :start-after: Display the port MAC address. > + :end-before: Enable RX in promiscuous mode for the Ethernet device. > + :dedent: 1 > + > + This would be rendered as: > + > + .. literalinclude:: ../../../examples/skeleton/basicfwd.c > + :language: c > + :start-after: Display the port MAC address. > + :end-before: Enable RX in promiscuous mode for the Ethernet device. > + :dedent: 1 > + > + Specifying ``:language:`` will enable syntax highlighting for the specified language. > + ``:dedent:`` is used in this example to remove 1 leading tab from each line of the snippet. > + > +* ``start-after`` and ``end-before`` can use any text within a given file, > + however it may be difficult to find unique text within your code to mark the > + start and end of your snippets. In these cases, it is recommended to include Such lenient attitude still leaves room for accidental changes (e.g. typo fixes, whitespace reformatting, language fixes etc.). I would've preferred the scissor syntax to be mandatory for all comment snippets for documentation. However, risk is pretty low so i can live with that :) > + explicit tags in your code to denote these locations for documentation purposes. > + The accepted format for these comments is: > + > + * Before the code snippet create a new comment, which is a sentence explaining > + what the code snippet contains. The comment is terminated with a scissors ``8<``. > + * After the code snippet create another new comment, which starts with a > + scissors ``>8``, then ``End of`` and the first comment repeated. > + * The scissors should be orientated as shown to make it clear what code is being snipped. > + > + This can be done as follows: > + > + .. code-block:: c > + > + /* Example feature being documented. 8< */ > + foo(bar); > + /* >8 End of example feature being documented. */ > + > + ``foo(bar);`` could then be included in the docs using:: > + > + .. literalinclude:: ../../../examples/sample_app/main.c > + :language: c > + :start-after: Example feature being documented. 8< > + :end-before: >8 End of example feature being documented. > + > + If a multiline comment is needed before the snippet then the last line of the > + multiline comment should be in the same format as the first comment shown > + in the example. > + > +* More information about the ``literalinclude`` block can be found within the > + `Sphinx Documentation `_. > > * The default encoding for a literal block using the simplified ``::`` > directive is ``none``. > Acked-by: Anatoly Burakov -- Thanks, Anatoly