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 <redacted>
---
doc/guides/contributing/documentation.rst | 45 +++++++++++++++++++++++
1 file changed, 45 insertions(+)
@@ -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``.
From: Mcnamara, John <hidden> Date: 2021-04-21 10:21:14
-----Original Message-----
From: Walsh, Conor <redacted>
Sent: Wednesday, April 21, 2021 10:12 AM
To: Mcnamara, John <redacted>; thomas@monjalon.net;
david.marchand@redhat.com; Yigit, Ferruh [off-list ref];
Richardson, Bruce [off-list ref]; Burakov, Anatoly
[off-list ref]
Cc: dev@dpdk.org; Walsh, Conor <redacted>
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 <redacted>
From: Thomas Monjalon <hidden> Date: 2021-04-21 10:31:26
21/04/2021 12:21, Mcnamara, John:
From: Walsh, Conor <redacted>
quoted
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.
From: Mcnamara, John <hidden> Date: 2021-04-21 14:17:57
-----Original Message-----
From: Thomas Monjalon <redacted>
Sent: Wednesday, April 21, 2021 11:31 AM
To: Walsh, Conor <redacted>; david.marchand@redhat.com;
Yigit, Ferruh [off-list ref]; Richardson, Bruce
[off-list ref]; Burakov, Anatoly
[off-list ref]; Mcnamara, John [off-list ref]
Cc: dev@dpdk.org
Subject: Re: [PATCH] doc/contributing/documentation: add info about
including code
quoted
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
From: David Marchand <hidden> Date: 2021-04-27 09:54:30
On Wed, Apr 21, 2021 at 11:12 AM Conor Walsh [off-list ref] 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.
From: Thomas Monjalon <hidden> Date: 2021-05-03 21:02:23
21/04/2021 11:11, Conor Walsh:
quoted hunk
+ 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.
[...]
quoted hunk
+* ``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
+ 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.
[...]
quoted
+* ``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
From: Thomas Monjalon <hidden> Date: 2021-05-04 09:59:29
04/05/2021 11:32, Burakov, Anatoly:
On 03-May-21 10:02 PM, Thomas Monjalon wrote:
quoted
21/04/2021 11:11, Conor Walsh:
quoted
+ 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.
[...]
quoted
+* ``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.
+ 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.
[...]
quoted
+* ``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.
From: Thomas Monjalon <hidden> Date: 2021-05-04 10:44:38
04/05/2021 12:35, Ferruh Yigit:
On 5/4/2021 10:59 AM, Thomas Monjalon wrote:
quoted
04/05/2021 11:32, Burakov, Anatoly:
quoted
On 03-May-21 10:02 PM, Thomas Monjalon wrote:
quoted
21/04/2021 11:11, Conor Walsh:
quoted
+ 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.
[...]
quoted
+* ``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.
+ 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.
[...]
quoted
+* ``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
From: Thomas Monjalon <hidden> Date: 2021-05-04 11:56:59
04/05/2021 13:15, Ferruh Yigit:
On 5/4/2021 11:44 AM, Thomas Monjalon wrote:
quoted
04/05/2021 12:35, Ferruh Yigit:
quoted
On 5/4/2021 10:59 AM, Thomas Monjalon wrote:
quoted
04/05/2021 11:32, Burakov, Anatoly:
quoted
On 03-May-21 10:02 PM, Thomas Monjalon wrote:
quoted
21/04/2021 11:11, Conor Walsh:
quoted
+ 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.
[...]
quoted
+* ``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.
+ 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.
[...]
quoted
+* ``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
+ The following will include a snippet from the skeleton sample
app::
quoted
quoted
quoted
quoted
quoted
quoted
quoted
quoted
++ .. 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.
quoted
quoted
quoted
quoted
quoted
quoted
quoted
quoted
+ :dedent: 1
I would prefer indenting the options with 3 spaces
to make them aligned with literalinclude.
I will update this in v2.
quoted
quoted
quoted
quoted
quoted
quoted
quoted
[...]
quoted
+* ``start-after`` and ``end-before`` can use any text within a given
file,
quoted
quoted
quoted
quoted
quoted
quoted
quoted
quoted
+ however it may be difficult to find unique text within your code
to mark the
quoted
quoted
quoted
quoted
quoted
quoted
quoted
quoted
+ start and end of your snippets. In these cases, it is
recommended to include
quoted
quoted
quoted
quoted
quoted
quoted
quoted
quoted
+ explicit tags in your code to denote these locations for
documentation purposes.
quoted
quoted
quoted
quoted
quoted
quoted
quoted
quoted
++ 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 */
quoted
quoted
quoted
quoted
quoted
quoted
quoted
.. 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:
quoted
quoted
quoted
quoted
quoted
quoted
quoted
/* 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.
quoted
quoted
quoted
quoted
quoted
quoted
Not having markup will 1) risk people accidentally "fixing" or
otherwise
quoted
quoted
quoted
quoted
quoted
quoted
modifying comments, and 2) has bigger potential for collisions
elsewhere
quoted
quoted
quoted
quoted
quoted
quoted
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.
quoted
quoted
quoted
quoted
quoted
quoted
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
quoted
quoted
quoted
quoted
quoted
quoted
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
quoted
quoted
quoted
quoted
comment is used for documentation purposes and use explicit syntax
for it.
quoted
quoted
quoted
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.
quoted
quoted
quoted
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 */
quoted
quoted
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
quoted
quoted
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
quoted
quoted
interested to go and check the relevant documentation
- Whoever reading the code, and not very familiar with DPDK convention,
still
quoted
quoted
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.
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 <redacted>
Acked-by: John McNamara <redacted>
Acked-by: David Marchand <redacted>
---
v2: indentation changes and moved to scissor syntax
---
doc/guides/contributing/documentation.rst | 56 +++++++++++++++++++++++
1 file changed, 56 insertions(+)
@@ -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``.
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 <redacted>
Acked-by: John McNamara <redacted>
Acked-by: David Marchand <redacted>
---
v2: indentation changes and moved to scissor syntax
---
doc/guides/contributing/documentation.rst | 56 +++++++++++++++++++++++
1 file changed, 56 insertions(+)
@@ -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 :)
quoted hunk
+ 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``.
From: Thomas Monjalon <hidden> Date: 2021-05-07 13:15:44
07/05/2021 11:54, Burakov, Anatoly:
On 06-May-21 5:40 PM, Conor Walsh wrote:
quoted
+* ``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.
quoted
+ explicit tags in your code to denote these locations for documentation purposes.
+ The accepted format for these comments is:
From: Thomas Monjalon <hidden> Date: 2021-05-19 21:37:02
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 <redacted>
Acked-by: John McNamara <redacted>
Acked-by: David Marchand <redacted>
Acked-by: Thomas Monjalon <redacted>
Applied, thanks.