Skip to content

Commit

Permalink
Improve markup in documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@AA-Turner
AA-Turner committed Jul 17, 2024
1 parent 56d7e10 commit e63c3f5
Show file tree
Hide file tree
Showing 10 changed files with 257 additions and 193 deletions.
14 changes: 9 additions & 5 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,14 +22,18 @@
:target: https://opensource.org/licenses/MIT
:alt: MIT

A sphinx extension that automatically documents argparse commands and options.
A Sphinx extension to automatically document argparse_ commands and options.

For installation and usage details see the documentation_.
The changelog is also `found there`_.

This project used to live at `alex-rudakov/sphinx-argparse`_,
and has been revived and moved to this new home.

.. _argparse: https://docs.python.org/3/library/argparse.html
.. _documentation: https://sphinx-argparse.readthedocs.org/
.. _found there: https://sphinx-argparse.readthedocs.org/en/latest/changelog.html
.. _alex-rudakov/sphinx-argparse: https://github.com/alex-rudakov/sphinx-argparse/

.. note::
This project used to live at `alex-rudakov/sphinx-argparse`_,
and has been revived and moved to this `new home`_.

.. _alex-rudakov/sphinx-argparse: https://github.com/alex-rudakov/sphinx-argparse/
.. _new home: https://github.com/sphinx-doc/sphinx-argparse/
18 changes: 9 additions & 9 deletions docs/changelog.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,8 +68,8 @@ Change log
0.2.3
#####

* Fixed a variety of issues, such as with `@replace` (issue #99). Thanks to @evgeni
* You can now skip sections with `@skip`. Thanks to @evgeni
* Fixed a variety of issues, such as with ``@replace`` (issue #99). Thanks to @evgeni
* You can now skip sections with ``@skip``. Thanks to @evgeni
* Fixed handling of the epilog

0.2.2
Expand All @@ -80,16 +80,16 @@ Change log
0.2.1
#####

* Stopped importing `sphinx.util.compat`, which was causing issues like that seen in `#65 <https://github.com/alex-rudakov/sphinx-argparse/issues/65>`_
* Stopped importing ``sphinx.util.compat``, which was causing issues like that seen in `#65 <https://github.com/alex-rudakov/sphinx-argparse/issues/65>`_

0.2.0
#####

* Section titles can now be used in tables of contents and linked to. The title itself is also used as the anchor. In the case of repeated names `_replicateX`, where `X` is a number, is prepended to ensure that all titles are uniquely linkable. This was bug `#46 <https://github.com/alex-rudakov/sphinx-argparse/issues/46>`_.
* Section titles can now be used in tables of contents and linked to. The title itself is also used as the anchor. In the case of repeated names ``_replicateX``, where ``X`` is a number, is prepended to ensure that all titles are uniquely linkable. This was bug `#46 <https://github.com/alex-rudakov/sphinx-argparse/issues/46>`_.
* The positional (aka required) and named (aka optional) option sections are now named "Positional Arguments" and "Named Arguments", for the sake of clarity (e.g., named arguments can be required). This was issue `#58 <https://github.com/alex-rudakov/sphinx-argparse/issues/58>`_.
* Fixed quoting of default strings (issue `#59 <https://github.com/alex-rudakov/sphinx-argparse/issues/59>`_).
* Added the `:noepilog:` and `:nodescription:` options, thanks to @arewm.
* Added the `:nosubcommand:` option, thanks to @arewm.
* Added the ``:noepilog:`` and ``:nodescription:`` options, thanks to @arewm.
* Added the ``:nosubcommand:`` option, thanks to @arewm.

0.1.17
######
Expand All @@ -99,9 +99,9 @@ Change log
0.1.16
######

* Added a `:nodefaultconst:` directive, which is similar to the `:nodefault:` directive, but applies only to `store_true`, `store_false`, and `store_const` (e.g., it will hide the "=True" part in the output, since that can be misleading to users).
* Added a ``:nodefaultconst:`` directive, which is similar to the ``:nodefault:`` directive, but applies only to ``store_true``, ``store_false``, and ``store_const`` (e.g., it will hide the "=True" part in the output, since that can be misleading to users).
* Fixed various typos (thanks to users mikeantonacci, brondsem, and tony)
* Format specifiers (e.g., `%(prog)s` and `%(default)s`) are now filled in (if possible) in help sections. If there's a missing keyword, then nothing will be filled in. This was issue #27.
* Format specifiers (e.g., ``%(prog)s`` and ``%(default)s``) are now filled in (if possible) in help sections. If there's a missing keyword, then nothing will be filled in. This was issue #27.
* The package is now a bit more robust to incorrectly spelling module names (#39, courtesy of Gabriel Falcão)
* Added support for argparse groups (thanks to Fidel Ramirez)

Expand All @@ -117,7 +117,7 @@ Change log
* Support for aliasing arguments #22 (Campbell Barton)
* Support for nested arguments #23 (Campbell Barton)
* Support for subcommand descriptions #24 (Campbell Barton)
* Improved parsing of content of `epilog` and `description` #25 (Louis - https://github.com/paternal)
* Improved parsing of content of ``epilog`` and ``description`` #25 (Louis - https://github.com/paternal)
* Added 'passparser' option (David Hoese)

0.1.13
Expand Down
17 changes: 11 additions & 6 deletions docs/contrib.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,17 @@ Any help is welcome!

Most wanted:

* Additional features
* Bug fixes
* Examples
* Additional features
* Bug fixes
* Examples

Contributions are gratefully accepted through `github <https://github.com/sphinx-doc/sphinx-argparse>`_ pull-request. Please report bugs as issues on github.
Contributions are gratefully accepted through `GitHub pull requests`_.
Please report any bugs as issues on GitHub.

Don't forget to run tests before committing::
.. _GitHub pull requests: https://github.com/sphinx-doc/sphinx-argparse/

py.test
Don't forget to run tests before committing:

.. code:: shell
pytest
79 changes: 44 additions & 35 deletions docs/extend.rst
View file
Original file line number Diff line number Diff line change
@@ -1,69 +1,78 @@
Extending results of `argparse` directives
==========================================
Extending results of ``argparse`` directives
============================================

You can add extra content or even replace some parts of the documentation generated by the `argparse` directive. For example, any content you put inside directives (you must follow ReStructuredText identation rules) will be inserted just before the argument and option list::
You can add extra content or even replace some parts of the documentation generated by the ``argparse`` directive.
For example, any content you put inside directives (you must follow ReStructuredText identation rules) will be inserted just before the argument and option list:

.. code:: rst
.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
My content here that will be inserted right before the argument list.
Also any valid markup...
*************************
... may `be` *applied* here
... may ``be`` *applied* here
including::
any directives you usually use.
Also, there is an option to insert custom content into a specific argument/option/subcommand/argument-group description. Just create a name:definition pair, where the name is an argument/option/subcommand/argument-group name and the definition is any reStructured markup. Changes to options/arguments appearing in multiple action groups can either be targeted (i.e., only one instance of the argument is changed) or general (i.e., all instances are modified).::
Also, there is an option to insert custom content into a specific argument/option/subcommand/argument-group description.
Just create a name:definition pair, where the name is an argument/option/subcommand/argument-group name and the definition is any reStructured markup.
Changes to options/arguments appearing in multiple action groups can either be targeted (i.e., only one instance of the argument is changed) or general (i.e., all instances are modified).

.. code:: rst
.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
My content here that will be inserted right before the argument list.
My content here that will be inserted right before the argument list.
foo
This text will go right after the "foo" positional argument help.
foo
This text will go right after the "foo" positional argument help.
install
This text will go right after the "install" subcommand help and before its arguments.
install
This text will go right after the "install" subcommand help and before its arguments.
--upgrade -u
This text will go after the upgrade option of the install subcommand. Nesting is unlimited.
Note the space between --upgrade and -u, which differs from the comma that would normally
be used.
--upgrade -u
This text will go after the upgrade option of the install subcommand. Nesting is unlimited.
Note the space between --upgrade and -u, which differs from the comma that would normally
be used.
--output -o
Content appended to the --output option, regardless of the argument group.
--output -o
Content appended to the --output option, regardless of the argument group.
You can also add classifiers, which will change how these definitions are incorporated:

You can also add classifiers, which will change how these definitions are incorporated::
.. code:: rst
.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
My content that will be inserted right before the argument list.
My content that will be inserted right before the argument list.
foo : @before
This text will go before the "foo" positional argument help.
foo : @before
This text will go before the "foo" positional argument help.
install : @replace
This text will replace the "install" subcommand help/description.
install : @replace
This text will replace the "install" subcommand help/description.
--upgrade : @after
The after directive is the default, so you needn't specify it.
--upgrade : @after
The after directive is the default, so you needn't specify it.
advanced arguments : @skip
skip advanced arguments
advanced arguments : @skip
skip advanced arguments
@before
Expand Down
36 changes: 22 additions & 14 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,16 @@
`sphinx-argparse`
=================

`sphinx-argparse` is an extension for sphinx that allows for easy generation of documentation for command line tools using the python argparse library.
``sphinx-argparse``
===================

`sphinx-argparse` is an extension for Sphinx_ that allows for
easy generation of documentation for command line tools using
Python's argparse_ library.

.. _Sphinx: https://www.sphinx-doc.org/
.. _argparse: https://docs.python.org/3/library/argparse.html

.. toctree::
:maxdepth: 2
:hidden:
:maxdepth: 1

usage
extend
Expand All @@ -22,15 +26,21 @@ Installation

This extension works with Python 3.10 or later and Sphinx 5.1 or later.

The package is available in the `Python Package Index`_::
The package is available in the `Python Package Index`_:

.. code:: shell
pip install sphinx-argparse
pip install sphinx-argparse
And also in `conda-forge`_:

And also in `conda-forge`_::
.. code:: shell
mamba -c conda-forge install sphinx-argparse
mamba -c conda-forge install sphinx-argparse
Enable the extension in your sphinx config::
Enable the extension in your sphinx config:

.. code:: python
extensions = [
...,
Expand All @@ -41,10 +51,8 @@ Enable the extension in your sphinx config::
.. _conda-forge: https:://github.com/conda-forge/sphinx-argparse-feedstock/


References
==========

Similar projects
-------------------

* https://pythonhosted.org/sphinxcontrib-autoprogram/ (See for comparison: https://github.com/ribozz/sphinx-argparse/issues/16)
* https://pypi.org/project/sphinxcontrib-autoprogram/
(See a comparison: https://github.com/sphinx-doc/sphinx-argparse/issues/16)
77 changes: 45 additions & 32 deletions docs/markdown.rst
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,33 @@
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::
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:

.. code:: rst
.. argparse::
:filename: ../test/sample.py
:func: parser
:prog: sample
:markdown:
:filename: ../test/sample.py
:func: parser
:prog: sample
:markdown:
Header 1
========
Header 1
========
[I'm a link to google](http://www.google.com)
[I'm a link to google](http://www.google.com)
## Sub-heading
## Sub-heading
```
This
is
a
fenced
code
block
```
```
This
is
a
fenced
code
block
```
The above example renders as follows:

Expand Down Expand Up @@ -51,42 +55,51 @@ The above example renders as follows:
block
```

The `CommonMark-py <https://github.com/rtfd/CommonMark-py>`__ is used internally to parse Markdown. Consequently, only Markdown supported by CommonMark-py will be rendered.
The `CommonMark-py <https://github.com/rtfd/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.
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 <http://daringfireball.net/projects/markdown/syntax#header>`__ and then rendered correctly.
If the Markdown you nest includes headings, then the first one **MUST** be level 1.
Subsequent headings can be at `lower levels <http://daringfireball.net/projects/markdown/syntax#header>`__ 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.
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 <extend.html>`__. This is because CommonMark-py does not support dictionary entries.
When markdown is used as nested content, it's not possible to create dictionary entries like in reStructuredText to `modify program option descriptions <extend.html>`__.
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::
In addition to using MarkDown in nested content, one can also use MarkDown directly in program descriptions and option help messages.
For example:

.. code:: python
import argparse
import argparse
def blah():
parser = argparse.ArgumentParser(description="""
### Example of MarkDown inside programs
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
[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:

To render this as MarkDown rather than reStructuredText, use the `markdownhelp` option::
.. code:: rst
.. argparse::
:filename: ../test/sample2.py
Expand Down
Loading

0 comments on commit e63c3f5

Please sign in to comment.