Improve markup in documentation

Author: AA-Turner

README.rst

@@ -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/

docs/changelog.rst

@@ -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
@@ -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
 ######
@@ -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)
 
@@ -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

docs/contrib.rst

@@ -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

docs/extend.rst

@@ -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

docs/index.rst

@@ -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
@@ -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 = [
         ...,
@@ -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)

docs/markdown.rst

@@ -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:
 
@@ -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