Add support for verbatim inline elements #560
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
utzig
force-pushed
the
inline-verbatim
branch
2 times, most recently
from
1bd2913
to
68890ca
Compare
utzig
force-pushed
the
inline-verbatim
branch
2 times, most recently
from
853952e
to
d3f9e12
Compare
This extends the current verbatim rST support with a new option "embed:rst:inline", which can be used to generate an inline node, instead of the paragraph node used by other verbatim blocks. Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
utzig
changed the title
* Update rst.h example with a function that includes an inline rST cpp domain link to another function using a verbatim * Update markups.rst with an inline verbatim section * Add Doxygen ALIAS to for an inline verbatim element Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
|
@vermeeren I believe this PR is also OK now, I will rebuild the Zephyr Project's documentation using this new feature and if I'll let you know afterwards. Btw, I tried to write some unit tests for this PR, but mocking the docutils statemachine soon turned out be not very reasonable! 🤣 |
Just rebuilt the Zephyr documentation with both this PR and #566 enabled and the results look pretty good! |
vermeeren
added
code
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This extends the current verbatim rST support with a new option "embed:rst:inline", which can be used to generate an inline node, instead of the paragraph node used by other verbatim blocks.
For a bit of perspective, for the Zephyr project (https://docs.zephyrproject.org/) and for Nordic's nRF Connect SDK (http://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/index.html), we use the
.. option:directive to create an entry for each existing configuration option in the kernel (and apps, libs, etc). For someone not acquainted this is very similar to configuration options in the Linux kernel (CONFIG_*).We refer a lot to those options over all the documentation. In rST it is straight-forward to do using:
But in Doxygen headers the only way to get those xrefs working was to use a
\verbatim, with the side-effect that it results in a<paragraph \>node, so it cannot be used inline.This PR allows for one to specify an option by using:
or by using a Doxygen alias:
just
@option{CONFIG_<some_option_name>}.