Markdown¶
As of version 0.2.0, markdown (rather than only reStructuredText) can be included inside directives as nested content. While markdown is much easier to write, please note that it is also less powerful. An example is below:
.. argparse::
:filename: ../test/sample.py
:func: parser
:prog: sample
:markdown:
Header 1
========
[I'm a link to google](http://www.google.com)
## Sub-heading
```
This
is
a
fenced
code
block
```
The above example renders as follows:
A random paragraph
Heading 1¶
Sub heading¶
This
is
a
fenced
code
block
usage: sample [-h] {apply,game} ...
Sub-commands¶
apply¶
Execute provision script, collect all resources and apply them.
sample apply [-h] [-r] [--tree] [--dry] [--force] path default_string
Positional Arguments¶
- path
Specify path to provision script. provision.py in current directory by default. Also may include url.
Default: “provision.py”
- default_string
Ensure variables are filled in (default “I am a default”)
Default: “I am a default”
Named Arguments¶
- -r, --rollback
If specified will rollback all resources applied.
Default: False
- --tree
Print resource tree
Default: False
- --dry
Just print changes list
Default: False
- --force
Apply without confirmation
Default: False
game¶
Decision games
sample game [-h] [--opt {rock,paper,scissors}] [--addition {Spock,lizard}]
[--lorem_ipsum LOREM_IPSUM]
{rock,paper,scissors}
Positional Arguments¶
- move
Possible choices: rock, paper, scissors
Choices for argument example
Named Arguments¶
- --opt
Possible choices: rock, paper, scissors
Choices for option example
Group 1¶
- --addition
Possible choices: Spock, lizard
Extra choices for additional group.
- --lorem_ipsum
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
The CommonMark-py is used internally to parse Markdown. Consequently, only Markdown supported by CommonMark-py will be rendered.
You must explicitly use the :markdown: flag, otherwise all content inside directives will be parsed as reStructuredText.
A note on headers¶
If the Markdown you nest includes headings, then the first one MUST be level 1. Subsequent headings can be at lower levels and then rendered correctly.
Hard line breaks¶
Sphinx strips white-space from the end of lines prior to handing it to this package. Because of that, hard line breaks can not currently be rendered.
Replacing/appending/prepending content¶
When markdown is used as nested content, it’s not possible to create dictionary entries like in reStructuredText to modify program option descriptions. This is because CommonMark-py does not support dictionary entries.
MarkDown in program descriptions and option help¶
In addition to using MarkDown in nested content, one can also use MarkDown directly in program descriptions and option help messages. For example:
import argparse
def blah():
parser = argparse.ArgumentParser(description="""
### Example of MarkDown inside programs
[I'm a link](http://www.google.com)
""")
parser.add_argument('cmd', help='execute a `command`')
return parser
To render this as MarkDown rather than reStructuredText, use the markdownhelp option:
.. argparse::
:filename: ../test/sample2.py
:func: blah
:prog: sample
:markdownhelp:
This will then be rendered as:
Example of MarkDown inside programs¶
usage: sample [-h] cmd
Positional Arguments¶
- cmd
execute a
command