doc/contributing/documentation: add info about including code
Checks
Commit Message
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
> -----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>
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.
> -----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
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 :)
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>
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
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
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.
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.
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.
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.
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
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.
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.
<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.
@@ -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``.