Re: [dpdk-dev] [PATCH] doc/contributing/documentation: add info about including code
flat view
From: Thomas Monjalon <hidden>
Date: 2021-05-03 21:02:23
21/04/2021 11:11, Conor Walsh:
quoted hunk ↗ jump to 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 ↗ jump to 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