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
