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

[Thomas Monjalon]

21/04/2021 11:11, Conor Walsh:
> +  The following will include a snippet from the skeleton sample app::
> +
> +      .. literalinclude:: ../../../examples/skeleton/basicfwd.c
> +        :language: c
> +        :start-after: Display the port MAC address.
> +        :end-before: Enable RX in promiscuous mode for the Ethernet device.
> +        :dedent: 1

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

[...]
> +* ``start-after`` and ``end-before`` can use any text within a given file,
> +  however it may be difficult to find unique text within your code to mark the
> +  start and end of your snippets. In these cases, it is recommended to include
> +  explicit tags in your code to denote these locations for documentation purposes.
> +
> +  This can be done as follows:
> +
> +  .. code-block:: c
> +
> +    /* #guide_doc: Example feature being documented. */
> +    ...
> +    /* #guide_doc: End of example feature being documented. */

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

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

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

Another idea:

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

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

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

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

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