[dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[Conor Walsh]

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.

Signed-off-by: Conor Walsh <conor.walsh@intel.com>
---
 doc/guides/contributing/documentation.rst | 45 +++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst
index a4e6be6aca..d5dd119a9a 100644
--- a/doc/guides/contributing/documentation.rst
+++ b/doc/guides/contributing/documentation.rst
@@ -433,6 +433,51 @@ 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
+  explicit tags in your code to denote these locations for documentation purposes.
+
+  This can be done as follows:
+
+  .. code-block:: c
+
+    /* #guide_doc: Example feature being documented. */
+    ...
+    /* #guide_doc: End of example feature being documented. */
+
+  ``...`` could then be included in the docs using::
+
+      .. literalinclude:: ../../../examples/sample_app/main.c
+        :language: c
+        :start-after: #guide_doc: Example feature being documented.
+        :end-before: #guide_doc: End of example feature being documented.
+
+* More information about the ``literalinclude`` block can be found within the
+  `Sphinx Documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html?highlight=literalinclude#directive-literalinclude>`_.
 
 * The default encoding for a literal block using the simplified ``::``
   directive is ``none``.
-- 
2.25.1

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[Mcnamara, John]

> -----Original Message-----
> From: Walsh, Conor <conor.walsh@intel.com>
> Sent: Wednesday, April 21, 2021 10:12 AM
> To: Mcnamara, John <john.mcnamara@intel.com>; thomas@monjalon.net;
> david.marchand@redhat.com; Yigit, Ferruh <ferruh.yigit@intel.com>;
> Richardson, Bruce <bruce.richardson@intel.com>; Burakov, Anatoly
> <anatoly.burakov@intel.com>
> Cc: dev@dpdk.org; Walsh, Conor <conor.walsh@intel.com>
> Subject: [PATCH] doc/contributing/documentation: add info about including
> code
> 
> 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.

This is a very good suggestion and I think we should encourage doc writers
to use this when including code in the documentation.

Acked-by: John McNamara <john.mcnamara@intel.com>

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[Thomas Monjalon]

21/04/2021 12:21, Mcnamara, John:
> From: Walsh, Conor <conor.walsh@intel.com>
> > 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.
> 
> This is a very good suggestion and I think we should encourage doc writers
> to use this when including code in the documentation.

Yes, and we should try to clean-up existing code snippets.

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[Mcnamara, John]

> -----Original Message-----
> From: Thomas Monjalon <thomas@monjalon.net>
> Sent: Wednesday, April 21, 2021 11:31 AM
> To: Walsh, Conor <conor.walsh@intel.com>; david.marchand@redhat.com;
> Yigit, Ferruh <ferruh.yigit@intel.com>; Richardson, Bruce
> <bruce.richardson@intel.com>; Burakov, Anatoly
> <anatoly.burakov@intel.com>; Mcnamara, John <john.mcnamara@intel.com>
> Cc: dev@dpdk.org
> Subject: Re: [PATCH] doc/contributing/documentation: add info about
> including code
> >
> > This is a very good suggestion and I think we should encourage doc
> > writers to use this when including code in the documentation.
> 
> Yes, and we should try to clean-up existing code snippets.

If there is no general objection to including code snippets this way then we could get someone to work on refactoring the sample code docs to use it.

John

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[Thomas Monjalon]

21/04/2021 16:17, Mcnamara, John:
> From: Thomas Monjalon <thomas@monjalon.net>
> > >
> > > This is a very good suggestion and I think we should encourage doc
> > > writers to use this when including code in the documentation.
> > 
> > Yes, and we should try to clean-up existing code snippets.
> 
> If there is no general objection to including code snippets this way
> then we could get someone to work on refactoring the sample code docs to use it.

I'd love such rework!
Removing lines is always good :)

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[David Marchand]

On Wed, Apr 21, 2021 at 4:21 PM Thomas Monjalon <thomas@monjalon.net> wrote:
>
> 21/04/2021 16:17, Mcnamara, John:
> > From: Thomas Monjalon <thomas@monjalon.net>
> > > >
> > > > This is a very good suggestion and I think we should encourage doc
> > > > writers to use this when including code in the documentation.
> > >
> > > Yes, and we should try to clean-up existing code snippets.
> >
> > If there is no general objection to including code snippets this way
> > then we could get someone to work on refactoring the sample code docs to use it.
>
> I'd love such rework!
> Removing lines is always good :)

+1 :-)

--
David Marchand

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[David Marchand]

On Wed, Apr 21, 2021 at 11:12 AM Conor Walsh <conor.walsh@intel.com> 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: We used literalinclude in the past and there was an issue with pdf:
https://git.dpdk.org/dpdk/commit/?id=d3ce1dc637c1bbef9a407f10281b2bc0549256da
But we don't generate pdf anymore, so we are good.

>
> Signed-off-by: Conor Walsh <conor.walsh@intel.com>
Acked-by: David Marchand <david.marchand@redhat.com>


-- 
David Marchand

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[Thomas Monjalon]

21/04/2021 11:11, Conor Walsh:
> +  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

I would prefer indenting the options with 3 spaces
to make them aligned with literalinclude.

[...]
> +* ``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
> +  explicit tags in your code to denote these locations for documentation purposes.
> +
> +  This can be done as follows:
> +
> +  .. code-block:: c
> +
> +    /* #guide_doc: Example feature being documented. */
> +    ...
> +    /* #guide_doc: End of example feature being documented. */

I think we can standardize this usage in a beautiful syntax.
My proposal, using the scissor sign:

    /* Foo bar >8 */
    foo(bar);
    /* 8< End of foo bar */

    .. literalinclude:: foobar.c
       :language: C
       :start-after: Foo bar >8
       :end-before: 8< End of foo bar

Another idea:

    /*~ Foo bar */
    foo(bar);
    /*~ End of foo bar */

    .. literalinclude:: foobar.c
       :language: C
       :start-after: ~ Foo bar
       :end-before: ~ End of foo bar

Maybe we don't need any markup for the start line and keep it natural:

    /* Foo bar */
    foo(bar);
    /* end: Foo bar */

    .. literalinclude:: foobar.c
       :language: C
       :start-after: Foo bar
       :end-before: end: Foo bar

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[Burakov, Anatoly]

On 03-May-21 10:02 PM, Thomas Monjalon wrote:
> 21/04/2021 11:11, Conor Walsh:
>> +  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
> 
> I would prefer indenting the options with 3 spaces
> to make them aligned with literalinclude.
> 
> [...]
>> +* ``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
>> +  explicit tags in your code to denote these locations for documentation purposes.
>> +
>> +  This can be done as follows:
>> +
>> +  .. code-block:: c
>> +
>> +    /* #guide_doc: Example feature being documented. */
>> +    ...
>> +    /* #guide_doc: End of example feature being documented. */
> 
> I think we can standardize this usage in a beautiful syntax.
> My proposal, using the scissor sign:
> 
>      /* Foo bar >8 */
>      foo(bar);
>      /* 8< End of foo bar */
> 
>      .. literalinclude:: foobar.c
>         :language: C
>         :start-after: Foo bar >8
>         :end-before: 8< End of foo bar
> 
> Another idea:
> 
>      /*~ Foo bar */
>      foo(bar);
>      /*~ End of foo bar */
> 
>      .. literalinclude:: foobar.c
>         :language: C
>         :start-after: ~ Foo bar
>         :end-before: ~ End of foo bar
> 
> Maybe we don't need any markup for the start line and keep it natural:
> 
>      /* Foo bar */
>      foo(bar);
>      /* end: Foo bar */
> 
>      .. literalinclude:: foobar.c
>         :language: C
>         :start-after: Foo bar
>         :end-before: end: Foo bar
> 
> 
> 
> 

Not having markup will 1) risk people accidentally "fixing" or otherwise 
modifying comments, and 2) has bigger potential for collisions elsewhere 
in the comments. While these aren't big risks, IMO it should be 
explicitly obvious that a comment is not just a comment but a marker docs.

Having named tags like in the original proposal is the most explicit 
version of the above, which is why i favor it, but i think it's OK to 
have a lighter-weight syntax (e.g. with scissors for example), however i 
don't think it's a good idea to leave things implicit like your last 
suggestion.

-- 
Thanks,
Anatoly

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[Thomas Monjalon]

04/05/2021 11:32, Burakov, Anatoly:
> On 03-May-21 10:02 PM, Thomas Monjalon wrote:
> > 21/04/2021 11:11, Conor Walsh:
> >> +  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
> > 
> > I would prefer indenting the options with 3 spaces
> > to make them aligned with literalinclude.
> > 
> > [...]
> >> +* ``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
> >> +  explicit tags in your code to denote these locations for documentation purposes.
> >> +
> >> +  This can be done as follows:
> >> +
> >> +  .. code-block:: c
> >> +
> >> +    /* #guide_doc: Example feature being documented. */
> >> +    ...
> >> +    /* #guide_doc: End of example feature being documented. */
> > 
> > I think we can standardize this usage in a beautiful syntax.
> > My proposal, using the scissor sign:
> > 
> >      /* Foo bar >8 */
> >      foo(bar);
> >      /* 8< End of foo bar */
> > 
> >      .. literalinclude:: foobar.c
> >         :language: C
> >         :start-after: Foo bar >8
> >         :end-before: 8< End of foo bar
> > 
> > Another idea:
> > 
> >      /*~ Foo bar */
> >      foo(bar);
> >      /*~ End of foo bar */
> > 
> >      .. literalinclude:: foobar.c
> >         :language: C
> >         :start-after: ~ Foo bar
> >         :end-before: ~ End of foo bar
> > 
> > Maybe we don't need any markup for the start line and keep it natural:
> > 
> >      /* Foo bar */
> >      foo(bar);
> >      /* end: Foo bar */
> > 
> >      .. literalinclude:: foobar.c
> >         :language: C
> >         :start-after: Foo bar
> >         :end-before: end: Foo bar
> 
> Not having markup will 1) risk people accidentally "fixing" or otherwise 
> modifying comments, and 2) has bigger potential for collisions elsewhere 
> in the comments. While these aren't big risks, IMO it should be 
> explicitly obvious that a comment is not just a comment but a marker docs.
> 
> Having named tags like in the original proposal is the most explicit 
> version of the above, which is why i favor it, but i think it's OK to 
> have a lighter-weight syntax (e.g. with scissors for example), however i 
> don't think it's a good idea to leave things implicit like your last 
> suggestion.

I think the first comment is not only for code extraction,
but also for code reader, that's why I think it's good to keep it natural.

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[Ferruh Yigit]

On 5/4/2021 10:59 AM, Thomas Monjalon wrote:
> 04/05/2021 11:32, Burakov, Anatoly:
>> On 03-May-21 10:02 PM, Thomas Monjalon wrote:
>>> 21/04/2021 11:11, Conor Walsh:
>>>> +  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
>>>
>>> I would prefer indenting the options with 3 spaces
>>> to make them aligned with literalinclude.
>>>
>>> [...]
>>>> +* ``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
>>>> +  explicit tags in your code to denote these locations for documentation purposes.
>>>> +
>>>> +  This can be done as follows:
>>>> +
>>>> +  .. code-block:: c
>>>> +
>>>> +    /* #guide_doc: Example feature being documented. */
>>>> +    ...
>>>> +    /* #guide_doc: End of example feature being documented. */
>>>
>>> I think we can standardize this usage in a beautiful syntax.
>>> My proposal, using the scissor sign:
>>>
>>>      /* Foo bar >8 */
>>>      foo(bar);
>>>      /* 8< End of foo bar */
>>>
>>>      .. literalinclude:: foobar.c
>>>         :language: C
>>>         :start-after: Foo bar >8
>>>         :end-before: 8< End of foo bar
>>>
>>> Another idea:
>>>
>>>      /*~ Foo bar */
>>>      foo(bar);
>>>      /*~ End of foo bar */
>>>
>>>      .. literalinclude:: foobar.c
>>>         :language: C
>>>         :start-after: ~ Foo bar
>>>         :end-before: ~ End of foo bar
>>>
>>> Maybe we don't need any markup for the start line and keep it natural:
>>>
>>>      /* Foo bar */
>>>      foo(bar);
>>>      /* end: Foo bar */
>>>
>>>      .. literalinclude:: foobar.c
>>>         :language: C
>>>         :start-after: Foo bar
>>>         :end-before: end: Foo bar
>>
>> Not having markup will 1) risk people accidentally "fixing" or otherwise 
>> modifying comments, and 2) has bigger potential for collisions elsewhere 
>> in the comments. While these aren't big risks, IMO it should be 
>> explicitly obvious that a comment is not just a comment but a marker docs.
>>
>> Having named tags like in the original proposal is the most explicit 
>> version of the above, which is why i favor it, but i think it's OK to 
>> have a lighter-weight syntax (e.g. with scissors for example), however i 
>> don't think it's a good idea to leave things implicit like your last 
>> suggestion.
> 
> I think the first comment is not only for code extraction,
> but also for code reader, that's why I think it's good to keep it natural.
> 
> 

+1 to Anatoly's comment, to make it obvious to the reader of the code that the
comment is used for documentation purposes and use explicit syntax for it.

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[Thomas Monjalon]

04/05/2021 12:35, Ferruh Yigit:
> On 5/4/2021 10:59 AM, Thomas Monjalon wrote:
> > 04/05/2021 11:32, Burakov, Anatoly:
> >> On 03-May-21 10:02 PM, Thomas Monjalon wrote:
> >>> 21/04/2021 11:11, Conor Walsh:
> >>>> +  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
> >>>
> >>> I would prefer indenting the options with 3 spaces
> >>> to make them aligned with literalinclude.
> >>>
> >>> [...]
> >>>> +* ``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
> >>>> +  explicit tags in your code to denote these locations for documentation purposes.
> >>>> +
> >>>> +  This can be done as follows:
> >>>> +
> >>>> +  .. code-block:: c
> >>>> +
> >>>> +    /* #guide_doc: Example feature being documented. */
> >>>> +    ...
> >>>> +    /* #guide_doc: End of example feature being documented. */
> >>>
> >>> I think we can standardize this usage in a beautiful syntax.
> >>> My proposal, using the scissor sign:
> >>>
> >>>      /* Foo bar >8 */
> >>>      foo(bar);
> >>>      /* 8< End of foo bar */
> >>>
> >>>      .. literalinclude:: foobar.c
> >>>         :language: C
> >>>         :start-after: Foo bar >8
> >>>         :end-before: 8< End of foo bar
> >>>
> >>> Another idea:
> >>>
> >>>      /*~ Foo bar */
> >>>      foo(bar);
> >>>      /*~ End of foo bar */
> >>>
> >>>      .. literalinclude:: foobar.c
> >>>         :language: C
> >>>         :start-after: ~ Foo bar
> >>>         :end-before: ~ End of foo bar
> >>>
> >>> Maybe we don't need any markup for the start line and keep it natural:
> >>>
> >>>      /* Foo bar */
> >>>      foo(bar);
> >>>      /* end: Foo bar */
> >>>
> >>>      .. literalinclude:: foobar.c
> >>>         :language: C
> >>>         :start-after: Foo bar
> >>>         :end-before: end: Foo bar
> >>
> >> Not having markup will 1) risk people accidentally "fixing" or otherwise 
> >> modifying comments, and 2) has bigger potential for collisions elsewhere 
> >> in the comments. While these aren't big risks, IMO it should be 
> >> explicitly obvious that a comment is not just a comment but a marker docs.
> >>
> >> Having named tags like in the original proposal is the most explicit 
> >> version of the above, which is why i favor it, but i think it's OK to 
> >> have a lighter-weight syntax (e.g. with scissors for example), however i 
> >> don't think it's a good idea to leave things implicit like your last 
> >> suggestion.
> > 
> > I think the first comment is not only for code extraction,
> > but also for code reader, that's why I think it's good to keep it natural.
> 
> +1 to Anatoly's comment, to make it obvious to the reader of the code that the
> comment is used for documentation purposes and use explicit syntax for it.

So you assume the comment is only for doc extraction?
I think it can be a real comment, otherwise we'll need to have
2 lines: 1 for doc extraction, 1 for code comment.

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[Ferruh Yigit]

On 5/4/2021 11:44 AM, Thomas Monjalon wrote:
> 04/05/2021 12:35, Ferruh Yigit:
>> On 5/4/2021 10:59 AM, Thomas Monjalon wrote:
>>> 04/05/2021 11:32, Burakov, Anatoly:
>>>> On 03-May-21 10:02 PM, Thomas Monjalon wrote:
>>>>> 21/04/2021 11:11, Conor Walsh:
>>>>>> +  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
>>>>>
>>>>> I would prefer indenting the options with 3 spaces
>>>>> to make them aligned with literalinclude.
>>>>>
>>>>> [...]
>>>>>> +* ``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
>>>>>> +  explicit tags in your code to denote these locations for documentation purposes.
>>>>>> +
>>>>>> +  This can be done as follows:
>>>>>> +
>>>>>> +  .. code-block:: c
>>>>>> +
>>>>>> +    /* #guide_doc: Example feature being documented. */
>>>>>> +    ...
>>>>>> +    /* #guide_doc: End of example feature being documented. */
>>>>>
>>>>> I think we can standardize this usage in a beautiful syntax.
>>>>> My proposal, using the scissor sign:
>>>>>
>>>>>      /* Foo bar >8 */
>>>>>      foo(bar);
>>>>>      /* 8< End of foo bar */
>>>>>
>>>>>      .. literalinclude:: foobar.c
>>>>>         :language: C
>>>>>         :start-after: Foo bar >8
>>>>>         :end-before: 8< End of foo bar
>>>>>
>>>>> Another idea:
>>>>>
>>>>>      /*~ Foo bar */
>>>>>      foo(bar);
>>>>>      /*~ End of foo bar */
>>>>>
>>>>>      .. literalinclude:: foobar.c
>>>>>         :language: C
>>>>>         :start-after: ~ Foo bar
>>>>>         :end-before: ~ End of foo bar
>>>>>
>>>>> Maybe we don't need any markup for the start line and keep it natural:
>>>>>
>>>>>      /* Foo bar */
>>>>>      foo(bar);
>>>>>      /* end: Foo bar */
>>>>>
>>>>>      .. literalinclude:: foobar.c
>>>>>         :language: C
>>>>>         :start-after: Foo bar
>>>>>         :end-before: end: Foo bar
>>>>
>>>> Not having markup will 1) risk people accidentally "fixing" or otherwise 
>>>> modifying comments, and 2) has bigger potential for collisions elsewhere 
>>>> in the comments. While these aren't big risks, IMO it should be 
>>>> explicitly obvious that a comment is not just a comment but a marker docs.
>>>>
>>>> Having named tags like in the original proposal is the most explicit 
>>>> version of the above, which is why i favor it, but i think it's OK to 
>>>> have a lighter-weight syntax (e.g. with scissors for example), however i 
>>>> don't think it's a good idea to leave things implicit like your last 
>>>> suggestion.
>>>
>>> I think the first comment is not only for code extraction,
>>> but also for code reader, that's why I think it's good to keep it natural.
>>
>> +1 to Anatoly's comment, to make it obvious to the reader of the code that the
>> comment is used for documentation purposes and use explicit syntax for it.
> 
> So you assume the comment is only for doc extraction?
> I think it can be a real comment, otherwise we'll need to have
> 2 lines: 1 for doc extraction, 1 for code comment.
> 

I see your point, for the cases that there is already a comment before (or
after) the code, will it be too bad to have multiple lines, something like:

/* Actual comment
 * More details
 *
 * explicit marker */


I think explicit marker has the advantage of:
- Whoever updating the comment will know that it is a marker for the
documentation and be careful on update
- Whoever updating the code between the markers, know that it may be required to
re-visit the relevant documentation and update it because of code change
- Whoever reading the code will know that part is in a documentation, and may be
interested to go and check the relevant documentation
- Whoever reading the code, and not very familiar with DPDK convention, still
can understand what that comment is for and benefit from above

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[Thomas Monjalon]

04/05/2021 13:15, Ferruh Yigit:
> On 5/4/2021 11:44 AM, Thomas Monjalon wrote:
> > 04/05/2021 12:35, Ferruh Yigit:
> >> On 5/4/2021 10:59 AM, Thomas Monjalon wrote:
> >>> 04/05/2021 11:32, Burakov, Anatoly:
> >>>> On 03-May-21 10:02 PM, Thomas Monjalon wrote:
> >>>>> 21/04/2021 11:11, Conor Walsh:
> >>>>>> +  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
> >>>>>
> >>>>> I would prefer indenting the options with 3 spaces
> >>>>> to make them aligned with literalinclude.
> >>>>>
> >>>>> [...]
> >>>>>> +* ``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
> >>>>>> +  explicit tags in your code to denote these locations for documentation purposes.
> >>>>>> +
> >>>>>> +  This can be done as follows:
> >>>>>> +
> >>>>>> +  .. code-block:: c
> >>>>>> +
> >>>>>> +    /* #guide_doc: Example feature being documented. */
> >>>>>> +    ...
> >>>>>> +    /* #guide_doc: End of example feature being documented. */
> >>>>>
> >>>>> I think we can standardize this usage in a beautiful syntax.
> >>>>> My proposal, using the scissor sign:
> >>>>>
> >>>>>      /* Foo bar >8 */
> >>>>>      foo(bar);
> >>>>>      /* 8< End of foo bar */
> >>>>>
> >>>>>      .. literalinclude:: foobar.c
> >>>>>         :language: C
> >>>>>         :start-after: Foo bar >8
> >>>>>         :end-before: 8< End of foo bar
> >>>>>
> >>>>> Another idea:
> >>>>>
> >>>>>      /*~ Foo bar */
> >>>>>      foo(bar);
> >>>>>      /*~ End of foo bar */
> >>>>>
> >>>>>      .. literalinclude:: foobar.c
> >>>>>         :language: C
> >>>>>         :start-after: ~ Foo bar
> >>>>>         :end-before: ~ End of foo bar
> >>>>>
> >>>>> Maybe we don't need any markup for the start line and keep it natural:
> >>>>>
> >>>>>      /* Foo bar */
> >>>>>      foo(bar);
> >>>>>      /* end: Foo bar */
> >>>>>
> >>>>>      .. literalinclude:: foobar.c
> >>>>>         :language: C
> >>>>>         :start-after: Foo bar
> >>>>>         :end-before: end: Foo bar
> >>>>
> >>>> Not having markup will 1) risk people accidentally "fixing" or otherwise 
> >>>> modifying comments, and 2) has bigger potential for collisions elsewhere 
> >>>> in the comments. While these aren't big risks, IMO it should be 
> >>>> explicitly obvious that a comment is not just a comment but a marker docs.
> >>>>
> >>>> Having named tags like in the original proposal is the most explicit 
> >>>> version of the above, which is why i favor it, but i think it's OK to 
> >>>> have a lighter-weight syntax (e.g. with scissors for example), however i 
> >>>> don't think it's a good idea to leave things implicit like your last 
> >>>> suggestion.
> >>>
> >>> I think the first comment is not only for code extraction,
> >>> but also for code reader, that's why I think it's good to keep it natural.
> >>
> >> +1 to Anatoly's comment, to make it obvious to the reader of the code that the
> >> comment is used for documentation purposes and use explicit syntax for it.
> > 
> > So you assume the comment is only for doc extraction?
> > I think it can be a real comment, otherwise we'll need to have
> > 2 lines: 1 for doc extraction, 1 for code comment.
> > 
> 
> I see your point, for the cases that there is already a comment before (or
> after) the code, will it be too bad to have multiple lines, something like:
> 
> /* Actual comment
>  * More details
>  *
>  * explicit marker */
> 
> 
> I think explicit marker has the advantage of:
> - Whoever updating the comment will know that it is a marker for the
> documentation and be careful on update
> - Whoever updating the code between the markers, know that it may be required to
> re-visit the relevant documentation and update it because of code change
> - Whoever reading the code will know that part is in a documentation, and may be
> interested to go and check the relevant documentation
> - Whoever reading the code, and not very familiar with DPDK convention, still
> can understand what that comment is for and benefit from above

I understand these points.
But I'm afraid the proposed syntax #guide_doc:
is not so obvious for everybody.

I'm sure there can be a better syntax.

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[Burakov, Anatoly]

On 04-May-21 12:56 PM, Thomas Monjalon wrote:
> 04/05/2021 13:15, Ferruh Yigit:
>> On 5/4/2021 11:44 AM, Thomas Monjalon wrote:
>>> 04/05/2021 12:35, Ferruh Yigit:
>>>> On 5/4/2021 10:59 AM, Thomas Monjalon wrote:
>>>>> 04/05/2021 11:32, Burakov, Anatoly:
>>>>>> On 03-May-21 10:02 PM, Thomas Monjalon wrote:
>>>>>>> 21/04/2021 11:11, Conor Walsh:
>>>>>>>> +  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
>>>>>>>
>>>>>>> I would prefer indenting the options with 3 spaces
>>>>>>> to make them aligned with literalinclude.
>>>>>>>
>>>>>>> [...]
>>>>>>>> +* ``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
>>>>>>>> +  explicit tags in your code to denote these locations for documentation purposes.
>>>>>>>> +
>>>>>>>> +  This can be done as follows:
>>>>>>>> +
>>>>>>>> +  .. code-block:: c
>>>>>>>> +
>>>>>>>> +    /* #guide_doc: Example feature being documented. */
>>>>>>>> +    ...
>>>>>>>> +    /* #guide_doc: End of example feature being documented. */
>>>>>>>
>>>>>>> I think we can standardize this usage in a beautiful syntax.
>>>>>>> My proposal, using the scissor sign:
>>>>>>>
>>>>>>>       /* Foo bar >8 */
>>>>>>>       foo(bar);
>>>>>>>       /* 8< End of foo bar */
>>>>>>>
>>>>>>>       .. literalinclude:: foobar.c
>>>>>>>          :language: C
>>>>>>>          :start-after: Foo bar >8
>>>>>>>          :end-before: 8< End of foo bar
>>>>>>>
>>>>>>> Another idea:
>>>>>>>
>>>>>>>       /*~ Foo bar */
>>>>>>>       foo(bar);
>>>>>>>       /*~ End of foo bar */
>>>>>>>
>>>>>>>       .. literalinclude:: foobar.c
>>>>>>>          :language: C
>>>>>>>          :start-after: ~ Foo bar
>>>>>>>          :end-before: ~ End of foo bar
>>>>>>>
>>>>>>> Maybe we don't need any markup for the start line and keep it natural:
>>>>>>>
>>>>>>>       /* Foo bar */
>>>>>>>       foo(bar);
>>>>>>>       /* end: Foo bar */
>>>>>>>
>>>>>>>       .. literalinclude:: foobar.c
>>>>>>>          :language: C
>>>>>>>          :start-after: Foo bar
>>>>>>>          :end-before: end: Foo bar
>>>>>>
>>>>>> Not having markup will 1) risk people accidentally "fixing" or otherwise
>>>>>> modifying comments, and 2) has bigger potential for collisions elsewhere
>>>>>> in the comments. While these aren't big risks, IMO it should be
>>>>>> explicitly obvious that a comment is not just a comment but a marker docs.
>>>>>>
>>>>>> Having named tags like in the original proposal is the most explicit
>>>>>> version of the above, which is why i favor it, but i think it's OK to
>>>>>> have a lighter-weight syntax (e.g. with scissors for example), however i
>>>>>> don't think it's a good idea to leave things implicit like your last
>>>>>> suggestion.
>>>>>
>>>>> I think the first comment is not only for code extraction,
>>>>> but also for code reader, that's why I think it's good to keep it natural.
>>>>
>>>> +1 to Anatoly's comment, to make it obvious to the reader of the code that the
>>>> comment is used for documentation purposes and use explicit syntax for it.
>>>
>>> So you assume the comment is only for doc extraction?
>>> I think it can be a real comment, otherwise we'll need to have
>>> 2 lines: 1 for doc extraction, 1 for code comment.
>>>
>>
>> I see your point, for the cases that there is already a comment before (or
>> after) the code, will it be too bad to have multiple lines, something like:
>>
>> /* Actual comment
>>   * More details
>>   *
>>   * explicit marker */
>>
>>
>> I think explicit marker has the advantage of:
>> - Whoever updating the comment will know that it is a marker for the
>> documentation and be careful on update
>> - Whoever updating the code between the markers, know that it may be required to
>> re-visit the relevant documentation and update it because of code change
>> - Whoever reading the code will know that part is in a documentation, and may be
>> interested to go and check the relevant documentation
>> - Whoever reading the code, and not very familiar with DPDK convention, still
>> can understand what that comment is for and benefit from above
> 
> I understand these points.
> But I'm afraid the proposed syntax #guide_doc:
> is not so obvious for everybody.
> 
> I'm sure there can be a better syntax.
> 

I'm not particularly attached to either syntax, as long as it's clearly 
documented and explicitly visible in the code (as opposed to something 
that kinda-sorta-but-doesn't-really-look-like-a-marker type syntax).

So, we'd have to give up some "natural-ness", as *that's the point* of 
having a syntax. And i'm certainly OK with comment style like this:

/*
  * some meaningful comment.
  * :doc_marker:
  */
...
/* :end doc_marker: */

Or something to that effect. What i'm *not* in favor of is these markers 
looking like part of a comment, rather than markers for doxygen.

-- 
Thanks,
Anatoly

Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code

[Walsh, Conor]

<snip>

> >>>>>>> 21/04/2021 11:11, Conor Walsh:
> >>>>>>>> +  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
> >>>>>>>
> >>>>>>> I would prefer indenting the options with 3 spaces
> >>>>>>> to make them aligned with literalinclude.

I will update this in v2.

> >>>>>>>
> >>>>>>> [...]
> >>>>>>>> +* ``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
> >>>>>>>> +  explicit tags in your code to denote these locations for
> documentation purposes.
> >>>>>>>> +
> >>>>>>>> +  This can be done as follows:
> >>>>>>>> +
> >>>>>>>> +  .. code-block:: c
> >>>>>>>> +
> >>>>>>>> +    /* #guide_doc: Example feature being documented. */
> >>>>>>>> +    ...
> >>>>>>>> +    /* #guide_doc: End of example feature being documented. */
> >>>>>>>
> >>>>>>> I think we can standardize this usage in a beautiful syntax.
> >>>>>>> My proposal, using the scissor sign:
> >>>>>>>
> >>>>>>>       /* Foo bar >8 */
> >>>>>>>       foo(bar);
> >>>>>>>       /* 8< End of foo bar */

I like the scissors syntax, I think its lightweight, clear and will help provide a unique string to search for.
I would switch the direction of the scissors so that the snippet is between the cuts to make it a bit clearer.
/* Foo bar 8< */
foo(bar);
/* >8 End of foo bar */

> >>>>>>>
> >>>>>>>       .. literalinclude:: foobar.c
> >>>>>>>          :language: C
> >>>>>>>          :start-after: Foo bar >8
> >>>>>>>          :end-before: 8< End of foo bar
> >>>>>>>
> >>>>>>> Another idea:
> >>>>>>>
> >>>>>>>       /*~ Foo bar */
> >>>>>>>       foo(bar);
> >>>>>>>       /*~ End of foo bar */
> >>>>>>>
> >>>>>>>       .. literalinclude:: foobar.c
> >>>>>>>          :language: C
> >>>>>>>          :start-after: ~ Foo bar
> >>>>>>>          :end-before: ~ End of foo bar
> >>>>>>>
> >>>>>>> Maybe we don't need any markup for the start line and keep it
> natural:
> >>>>>>>
> >>>>>>>       /* Foo bar */
> >>>>>>>       foo(bar);
> >>>>>>>       /* end: Foo bar */
> >>>>>>>
> >>>>>>>       .. literalinclude:: foobar.c
> >>>>>>>          :language: C
> >>>>>>>          :start-after: Foo bar
> >>>>>>>          :end-before: end: Foo bar

I think it definitely needs some syntax so that people realise it isn’t just a normal comment.

> >>>>>>
> >>>>>> Not having markup will 1) risk people accidentally "fixing" or
> otherwise
> >>>>>> modifying comments, and 2) has bigger potential for collisions
> elsewhere
> >>>>>> in the comments. While these aren't big risks, IMO it should be
> >>>>>> explicitly obvious that a comment is not just a comment but a marker
> docs.
> >>>>>>
> >>>>>> Having named tags like in the original proposal is the most explicit
> >>>>>> version of the above, which is why i favor it, but i think it's OK to
> >>>>>> have a lighter-weight syntax (e.g. with scissors for example),
> however i
> >>>>>> don't think it's a good idea to leave things implicit like your last
> >>>>>> suggestion.
> >>>>>
> >>>>> I think the first comment is not only for code extraction,
> >>>>> but also for code reader, that's why I think it's good to keep it natural.
> >>>>
> >>>> +1 to Anatoly's comment, to make it obvious to the reader of the code
> that the
> >>>> comment is used for documentation purposes and use explicit syntax
> for it.
> >>>
> >>> So you assume the comment is only for doc extraction?

I think the comments added as part of this should be meaningful comments that include the scissors syntax.
If there is already a multiline comment present then the last line should be the name of the feature or something short with the scissors syntax.

> >>> I think it can be a real comment, otherwise we'll need to have
> >>> 2 lines: 1 for doc extraction, 1 for code comment.
> >>>
> >>
> >> I see your point, for the cases that there is already a comment before (or
> >> after) the code, will it be too bad to have multiple lines, something like:
> >>
> >> /* Actual comment
> >>   * More details
> >>   *
> >>   * explicit marker */

I can add an example that cover this case in v2.
/* Comments
  * More comments
  *
  * Foo Bar 8< */
foo(bar);
/* >8 End of foo bar */

> >>
> >>
> >> I think explicit marker has the advantage of:
> >> - Whoever updating the comment will know that it is a marker for the
> >> documentation and be careful on update
> >> - Whoever updating the code between the markers, know that it may be
> required to
> >> re-visit the relevant documentation and update it because of code change
> >> - Whoever reading the code will know that part is in a documentation, and
> may be
> >> interested to go and check the relevant documentation
> >> - Whoever reading the code, and not very familiar with DPDK convention,
> still
> >> can understand what that comment is for and benefit from above
> >
> > I understand these points.
> > But I'm afraid the proposed syntax #guide_doc:
> > is not so obvious for everybody.
> >
> > I'm sure there can be a better syntax.
> >
> 
> I'm not particularly attached to either syntax, as long as it's clearly
> documented and explicitly visible in the code (as opposed to something
> that kinda-sorta-but-doesn't-really-look-like-a-marker type syntax).
> 
> So, we'd have to give up some "natural-ness", as *that's the point* of
> having a syntax. And i'm certainly OK with comment style like this:
> 
> /*
>   * some meaningful comment.
>   * :doc_marker:
>   */
> ...
> /* :end doc_marker: */
> 
> Or something to that effect. What i'm *not* in favor of is these markers
> looking like part of a comment, rather than markers for doxygen.

I agree I think the scissors syntax would be a good mix between having a marker and keeping it as a natural comment while also showing that it isn’t a standard comment.

Thanks for everyone's feedback and input.
I will send a v2 based on these comments.

Thanks,
Conor.

[dpdk-dev] [PATCH v2] doc/contributing/doc: add info about including code

[Conor Walsh]

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 <conor.walsh@intel.com>
Acked-by: John McNamara <john.mcnamara@intel.com>
Acked-by: David Marchand <david.marchand@redhat.com>

---

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
+  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 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html?highlight=literalinclude#directive-literalinclude>`_.
 
 * The default encoding for a literal block using the simplified ``::``
   directive is ``none``.
-- 
2.25.1

Re: [dpdk-dev] [PATCH v2] doc/contributing/doc: add info about including code

[Burakov, Anatoly]

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 <conor.walsh@intel.com>
> Acked-by: John McNamara <john.mcnamara@intel.com>
> Acked-by: David Marchand <david.marchand@redhat.com>
> 
> ---
> 
> 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 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html?highlight=literalinclude#directive-literalinclude>`_.
>   
>   * The default encoding for a literal block using the simplified ``::``
>     directive is ``none``.
> 

Acked-by: Anatoly Burakov <anatoly.burakov@intel.com>

-- 
Thanks,
Anatoly

Re: [dpdk-dev] [PATCH v2] doc/contributing/doc: add info about including code

[Thomas Monjalon]

07/05/2021 11:54, Burakov, Anatoly:
> On 06-May-21 5:40 PM, Conor Walsh wrote:
> > +* ``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 :)

Compiling the documentation is part of any reasonnable test,
so the risk is very low.

> > +  explicit tags in your code to denote these locations for documentation purposes.
> > +  The accepted format for these comments is:

Re: [dpdk-dev] [PATCH v2] doc/contributing/doc: add info about including code

[Thomas Monjalon]

06/05/2021 18:40, Conor Walsh:
> 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 <conor.walsh@intel.com>
> Acked-by: John McNamara <john.mcnamara@intel.com>
> Acked-by: David Marchand <david.marchand@redhat.com>

Acked-by: Thomas Monjalon <thomas@monjalon.net>

Applied, thanks.