diff mbox series

doc/contributing/documentation: add info about including code

Message ID 20210421091146.1384708-1-conor.walsh@intel.com (mailing list archive)
State Superseded
Delegated to: Thomas Monjalon
Headers show
Series doc/contributing/documentation: add info about including code | expand

Checks

Context Check Description
ci/intel-Testing success Testing PASS
ci/Intel-compilation success Compilation OK
ci/github-robot success github build: passed
ci/checkpatch warning coding style issues

Commit Message

Walsh, Conor April 21, 2021, 9:11 a.m. UTC
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(+)

Comments

Mcnamara, John April 21, 2021, 10:21 a.m. UTC | #1
> -----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>
Thomas Monjalon April 21, 2021, 10:31 a.m. UTC | #2
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.
Mcnamara, John April 21, 2021, 2:17 p.m. UTC | #3
> -----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
Thomas Monjalon April 21, 2021, 2:21 p.m. UTC | #4
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 :)
David Marchand April 27, 2021, 9:54 a.m. UTC | #5
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 April 27, 2021, 9:54 a.m. UTC | #6
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
Thomas Monjalon May 3, 2021, 9:02 p.m. UTC | #7
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
Burakov, Anatoly May 4, 2021, 9:32 a.m. UTC | #8
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.
Thomas Monjalon May 4, 2021, 9:59 a.m. UTC | #9
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.
Ferruh Yigit May 4, 2021, 10:35 a.m. UTC | #10
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.
Thomas Monjalon May 4, 2021, 10:44 a.m. UTC | #11
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.
Ferruh Yigit May 4, 2021, 11:15 a.m. UTC | #12
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
Thomas Monjalon May 4, 2021, 11:56 a.m. UTC | #13
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.
Burakov, Anatoly May 5, 2021, 12:02 p.m. UTC | #14
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.
Walsh, Conor May 6, 2021, 1:50 p.m. UTC | #15
<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.
diff mbox series

Patch

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``.