How can I embed code into a docstring to tell Sphinx to format the code similar as it will be done in Markdown (different background colour, monospaced sans-serif font)? For example to document a code usage example. """ This is a module documentation Use this module like this: res = aFunction(something, goes, in) print(res.avalue) """ ... There are a few ways to do it. I think the most sensible in your case would be .. code-block... More on stackoverflow.com

For example: def foo(): ''' .. highlight:: python import sys ''' Doesn't produce desired output (it prints the word "highlight" verbatim and doesn't format the following code in any More on stackoverflow.com

I would like to nest code blocks in a docstring: /// You can use the following template to document your function: /// /// ```text /// This function does things. /// ```text /// inner block of text /// ``` /// It is a cool function. /// ``` /// /// When using the template above, be sure to ... More on users.rust-lang.org

Docstrings are easily obtainable by other Python tools dynamically just by inspecting your objects. This is useful for tools that do things like generating API documentation. Comments are, by comparison, more difficult for such tools to use in part because comments are discarded by the compiler whereas docstrings are a part of your object (see .__doc__ attribute of any function, class, etc.). They're not necessarily interchangable tools, however. They're different tools for different purposes. Also, docstrings only work in certain places like at the very beginning of modules, classes, or functions. Comments, on the other hand, can be placed anywhere. More on reddit.com