[Python-modules-commits] [sphinx-argparse] 04/12: Import sphinx-argparse_0.2.1.orig.tar.gz
ChangZhuo Chen
czchen at moszumanska.debian.org
Sun Jul 2 13:21:32 UTC 2017
This is an automated email from the git hooks/post-receive script.
czchen pushed a commit to branch master
in repository sphinx-argparse.
commit 72f60cadb98011b937a169422dfe7cbdbc27d931
Author: ChangZhuo Chen (陳昌倬) <czchen at debian.org>
Date: Sun Jul 2 20:52:11 2017 +0800
Import sphinx-argparse_0.2.1.orig.tar.gz
---
.gitignore | 1 +
.travis.yml | 15 +-
README.md | 70 ++++++---
docs/conf.py | 12 +-
docs/contrib.rst | 25 ++-
docs/extend.rst | 49 +++---
docs/index.rst | 11 +-
docs/install.rst | 11 +-
docs/markdown.rst | 104 ++++++++++++
docs/misc.rst | 27 ++++
docs/sample.rst | 45 +++---
docs/usage.rst | 56 ++++---
requirements.txt | 0
requirements_dev.txt | 1 +
requirements_rtd.txt | 3 +
setup.py | 27 ++--
sphinxarg/__init__.py | 1 +
sphinxarg/ext.py | 426 ++++++++++++++++++++++++++++++++------------------
sphinxarg/markdown.py | 398 ++++++++++++++++++++++++++++++++++++++++++++++
sphinxarg/parser.py | 167 +++++++++++++-------
test/sample.py | 23 +--
test/sample2.py | 11 ++
test/test_parser.py | 234 +++++++++++++++++++--------
23 files changed, 1288 insertions(+), 429 deletions(-)
diff --git a/.gitignore b/.gitignore
index c4ae962..681d0f1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -37,3 +37,4 @@ nosetests.xml
.env/
docs/_build/
+.cache/
diff --git a/.travis.yml b/.travis.yml
index e578271..74f1659 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -1,15 +1,14 @@
language: python
python:
- - "2.6"
- "2.7"
- "3.3"
+ - "3.4"
+ - "3.5"
+ - "3.6"
install:
-- "pip install -e .[dev] --use-mirrors"
+ - pip install .
+ - pip install flake8
script:
-- py.test
-
-notifications:
- email:
- recipients:
- - ribozz at gmail.com
\ No newline at end of file
+ - py.test
+ - flake8 . --ignore=E501 --exclude=docs/conf.py
diff --git a/README.md b/README.md
index 0cdd052..62797f8 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,51 @@
+[](https://travis-ci.org/ribozz/sphinx-argparse) [](http://sphinx-argparse.readthedocs.org/) [](https://badge.fury.io/py/sphinx-argparse) [Install with conda](https://anaconda.org/conda-forge/sphinx-argparse/badges/installer/conda.svg) [Conda downloads](htt [...]
+
sphinx-argparse
===============
-Sphinx extension that automatically document argparse commands and options
+A sphinx extension that automatically documents argparse commands and options.
-For installation and usage details see docs.
+For installation and usage details see the [documentation](http://sphinx-argparse.readthedocs.org/en/latest/).
-Documnetation is here:
-http://sphinx-argparse.readthedocs.org/en/latest/
+Changelog & contributors
+========================
+0.2.1
+-----
-Changelog & contributors
-------------------------------
+ * Stopped importing `sphinx.util.compat`, which was causing issues like that seen in [#65](https://github.com/ribozz/sphinx-argparse/issues/65)
-0.1.15
+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.
+- 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.
+- Fixed quoting of default strings (issue #59).
+- Added the `:noepilogue:` and `:nodescription:` options, thanks to @arewm.
+- Added the `:nosubcommand:` option, thanks to @arewm.
+
+0.1.17
+------
+
+- Fixed handling of argument groups (this was bug #49). Thanks to @croth1 for reporting this bug. Note that now position arguments (also known as required arguments) within argument groups are now also handled correctly.
-------------------------------
+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).
+- 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.
+- 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)
+
+0.1.15
+------
- Fixed malformed docutils DOM in manpages (Matt Boyer)
0.1.14
-
------------------------------
+------
- Support for aliasing arguments #22 (Campbell Barton)
- Support for nested arguments #23 (Campbell Barton)
@@ -30,69 +54,67 @@ Changelog & contributors
- Added 'passparser' option (David Hoese)
0.1.13
-
------------------------------
+------
- Bugfix: Choices are not always strings (Robert Langlois)
- Polished small mistakes in usage documentation (Dean Malmgren)
- Started to improve man-pages support (Zygmunt Krynicki)
-------------------------------
0.1.12
+------
- Improved error reporting (James Anderson)
-------------------------------
0.1.11
+------
- Fixed stupid bug, prevented things working on py3 (Alex Rudakov)
- added tox configuration for tests
-------------------------------
0.1.10
+------
- Remove the ugly new line in the end of usage string (Vadim Markovtsev)
- Issue #9 Display argument choises (Proposed by Felix-neko, done by Alex Rudakov)
- :ref: syntax for specifying path to parser instance. Issue #7 (Proposed by David Cottrell, Implemented by Alex Rudakov)
- Updated docs to read the docs theme
-------------------------------
0.1.9
+-----
Fix problem with python version comparison, when python reports it as "2.7.5+" (Alex Rudakov)
-------------------------------
0.1.8
+-----
Argparse is not required anymore separate module as of python 2.7 (Mike Gleen)
-------------------------------
0.1.7
+-----
-- Nothing -- Created by axident.
-------------------------------
0.1.6
+-----
Adding :nodefault: directive that skips default values for options (Stephen Tridgell)
-------------------------------
0.1.5
+-----
Fix issue: epilog is ignored (James Anderson - https://github.com/jamesra)
-------------------------------
0.1.4
+-----
Fix issue #3: ==SUPPRESS== in option list with no default value
-------------------------------
0.1.2
+-----
Fix issue with subcommands (by Tony Narlock - https://github.com/tony)
-------------------------------
0.1.1
+-----
Initial version
-
diff --git a/docs/conf.py b/docs/conf.py
index c4bb9cc..30a85a6 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -18,7 +18,7 @@ import sys, os
# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('..'))
+#sys.path.insert(0, os.path.abspath('..'))
# -- General configuration -----------------------------------------------------
@@ -52,7 +52,7 @@ master_doc = 'index'
# General information about the project.
project = u'sphinx-argparse'
-copyright = u'2013, Alex Rudakov'
+copyright = u'2017, Alex Rudakov, Devon Ryan and contributors'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -134,7 +134,7 @@ pygments_style = 'sphinx'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
@@ -198,7 +198,7 @@ latex_elements = {
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'sphinx-argparse.tex', u'sphinx-argparse Documentation',
- u'Alex Rudakov', 'manual'),
+ u'Alex Rudakov and Devon Ryan', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
@@ -228,7 +228,7 @@ latex_documents = [
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'sphinx-argparse', u'sphinx-argparse Documentation',
- [u'Alex Rudakov'], 1)
+ [u'Alex Rudakov', u'Devon Ryan'], 1)
]
# If true, show URL addresses after external links.
@@ -242,7 +242,7 @@ man_pages = [
# dir menu entry, description, category)
texinfo_documents = [
('index', 'sphinx-argparse', u'sphinx-argparse Documentation',
- u'Alex Rudakov', 'sphinx-argparse', 'One line description of project.',
+ u'Alex Rudakov and Devon Ryan', 'sphinx-argparse', 'One line description of project.',
'Miscellaneous'),
]
diff --git a/docs/contrib.rst b/docs/contrib.rst
index 43471c6..4f72987 100644
--- a/docs/contrib.rst
+++ b/docs/contrib.rst
@@ -1,23 +1,16 @@
-
-
-
-Contribution
------------------------------------------
+Contribute
+==========
Any help is welcome!
-Most wanted:
-* documentation correction (I am not native english speaker)
-* bugfixes
-* examples
-* ports for other libraries (optparse, what else?)
-Contributions are accepted through github pull-request.
-Bug reports are also through bug-tracker on github.
+Most wanted:
-https://github.com/ribozz/sphinx-argparse
+ * Additional features
+ * Bug fixes
+ * Examples
-Don't forget to run tests before commit::
+Contributions are gratefully accepted through `github <https://github.com/ribozz/sphinx-argparse>`_ pull-request. Please report bugs as issues on github.
- py.test`
+Don't forget to run tests before committing::
-Any feedback is welcome: ribozz (a) gmail dot com
\ No newline at end of file
+ py.test
diff --git a/docs/extend.rst b/docs/extend.rst
index 6475bd8..ef9123a 100644
--- a/docs/extend.rst
+++ b/docs/extend.rst
@@ -1,19 +1,14 @@
+Extending results of `argparse` directives
+==========================================
-
-
-
-Extending result of `argparse` directive
------------------------------------------
-
-You can add extra content or even replace some part of documentation generated by `argparse` directive.
-For example, any content you put inside directive (follow reText identation rules), will be inserted, just before 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::
.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
- My content here that will be inserted as extra, right before argument list.
+ My content here that will be inserted right before the argument list.
Also any valid markup...
*************************
@@ -25,52 +20,54 @@ For example, any content you put inside directive (follow reText identation rule
any directives you usually use.
-Also, there is an option to insert own content into argument/option/subcommand description. Just create definition-list,
-where name is argument/option/subcommand name and definition-body is any reStructured markup::
+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 targetted (i.e., only one instance of the argument is changed) or general (i.e., all instances are modified).::
.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
- My content here that will be inserted as extra right before argument list.
+ My content here that will be inserted right before the argument list.
foo
- This text will go right after "foo" positional argument help.
+ This text will go right after the "foo" positional argument help.
install
- This text will go right after "install" subcommand help and before it's arguments.
+ 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
- This text will go to upgrade option of install subcommand, nesting is not limited
+ --output -o
+ Content appended to the --output option, regardless of the argument group.
-You can also add classifiers to definition-list that will change behavior of content merge algorythm::
+You can also add classifiers, which will change how these definitions are incorporated::
.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
- My content that will be inserted as extra, right before argument list.
+ My content that will be inserted right before the argument list.
foo : @before
- This text will go right after "foo" positional argument help.
+ This text will go before the "foo" positional argument help.
install : @replace
- This text will go right after "install" subcommand help and befor it's arguments.
+ This text will replace the "install" subcommand help/description.
--upgrade : @after
- This text will go to upgrade option of install subcommand, nesting is not limited
+ The after directive is the default, so you needn't specify it.
@before
- Insert content before parsed help message of argument/option/subcommand.
+ Insert content before the parsed help/description message of the argument/option/subcommand/argument-group.
@after
- Insert content after parsed help message of argument/option/subcommand.
-
- This is default, if you do not specify classifier explicitly.
+ Insert content after the parsed help/description message of argument/option/subcommand/argument-group. This is the default.
@replace
- Replace content of help message of argument/option/subcommand.
+ Replace content of help/description message of argument/option/subcommand/argument-group.
diff --git a/docs/index.rst b/docs/index.rst
index 0c362cd..68ea033 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,8 +1,7 @@
`sphinx-argparse`
-=============================================================
+=================
-`sphinx-argparse` is extension for sphinx that allows easily generate documentation
-for command line tools based on argparse library.
+`sphinx-argparse` is an extension for sphinx that allows for easy generation of documentation for command line tools using the python argparse library.
@@ -13,16 +12,16 @@ for command line tools based on argparse library.
usage
extend
sample
+ misc
+ markdown
contrib
References
-==================
+==========
Similar projects
-------------------
* https://pythonhosted.org/sphinxcontrib-autoprogram/ (See for comparison: https://github.com/ribozz/sphinx-argparse/issues/16)
-
-
diff --git a/docs/install.rst b/docs/install.rst
index 8c424e6..97fdf21 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -1,15 +1,12 @@
-
-
Installation
-------------
+============
-This extension is tested on python 2.7. If you have successfully used it on any other version
-of python, then add this info to this doc please (through gihtub pull reuqest).
+This extension is tested on python 2.7 and 3.3+.
-Package is available in the Python Package Index::
+The package is available in the Python Package Index::
pip install sphinx-argparse
-Enable extension in your sphinx config::
+Enable the extension in your sphinx config::
extensions += ['sphinxarg.ext']
diff --git a/docs/markdown.rst b/docs/markdown.rst
new file mode 100644
index 0000000..d02f713
--- /dev/null
+++ b/docs/markdown.rst
@@ -0,0 +1,104 @@
+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:
+
+.. argparse::
+ :filename: ../test/sample.py
+ :func: parser
+ :prog: sample
+ :markdown:
+
+ A random paragraph
+
+ Heading 1
+ =========
+
+ [I'm a link to google](http://www.google.com)
+
+ ## Sub heading
+
+ ```
+ This
+ is
+ a
+ fenced
+ code
+ 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.
+
+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.
+
+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 <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::
+
+ 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:
+
+.. argparse::
+ :filename: ../test/sample2.py
+ :func: blah
+ :prog: sample
+ :markdownhelp:
+
diff --git a/docs/misc.rst b/docs/misc.rst
new file mode 100644
index 0000000..cf75a35
--- /dev/null
+++ b/docs/misc.rst
@@ -0,0 +1,27 @@
+Miscellaneous
+=============
+
+Text wrapping in argument tables
+--------------------------------
+
+A common issue with the default html output is that the table within which options are displayed is designed such that the option descriptions are each held on one line. Any even remotely lengthy description then causes the viewer to need to scroll left/right to view the entire text. This is typically undesirable and the fix is described fully `here <http://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html>`_.
+
+The short synopsis is below:
+
+ 1. Create a new CSS file (likely under `_static`) and point to it in `html_static_path` and `html_context` (or a template in the `templates_path`) in `conf.py`.
+ 2. In that CSS file, add the following code:
+
+ .. code:: CSS
+
+ .wy-table-responsive table td {
+ white-space: normal !important;
+ }
+ .wy-table-responsive {
+ overflow: visible !important;
+ }
+
+
+Linking to action groups
+------------------------
+
+As of version 0.2.0, action groups (e.g., "Optional arguments", "Required arguments", and subcommands) can be included in tables of contents and external links. The anchor name is the same as the title name (e.g., "Optional arguments"). In cases where titles are duplicated, as is often the case when subcommands are used, `_repeatX`, where `X` is a number, is prepended to duplicate anchor names to ensure that they can all be uniquely linked.
diff --git a/docs/sample.rst b/docs/sample.rst
index cee4109..f2d525f 100644
--- a/docs/sample.rst
+++ b/docs/sample.rst
@@ -1,11 +1,10 @@
-==============
Examples
-==============
+========
-Example structure of pages
-=============================
+Example documentation structure
+-------------------------------
-Here is example structure of documentation for complex commands with lots of subcommands.
+Here is an example structure for the documentation of a complex command with many subcommands.
You are free to use any structure, but this may be a good starting point.
File "index.rst"::
@@ -18,8 +17,8 @@ File "index.rst"::
File "cmd.rst"::
- Command line utitlites
- ***********************
+ Command line utilities
+ **********************
.. toctree::
:maxdepth: 1
@@ -36,11 +35,11 @@ File "cmd_main.rst"::
.. argparse::
:module: my.module
- :func: my_func_that_return_parser
+ :func: my_func_that_returns_a_parser
:prog: fancytool
subcommand
- Here we add reference to subcommand, to simplify navigation.
+ Here we add a reference to subcommand, to simplify navigation.
See :doc:`cmd_subcommand`
@@ -57,7 +56,7 @@ File "cmd_subcommand.rst"::
Source of example file
-===========================
+----------------------
This file will be used in all generated examples.
@@ -65,44 +64,46 @@ This file will be used in all generated examples.
Generated sample 1 - command with subcommands
-================================================
+---------------------------------------------
Directive
-----------------
+~~~~~~~~~
Source::
.. argparse::
- :ref: test.sample.parser
+ :filename: ../test/sample.py
+ :func: parser
:prog: sample
Output
-----------------
+~~~~~~
.. argparse::
- :ref: test.sample.parser
- :prog: sample
+ :filename: ../test/sample.py
+ :func: parser
+ :prog: sample
Generated sample 2 - subcommand
-==================================
+-------------------------------
Directive
-----------------
+~~~~~~~~~
Source::
.. argparse::
- :module: test.sample
+ :filename../test/sample.py
:func: parser
:prog: sample
:path: game
Output
-----------------
+~~~~~~
.. argparse::
- :module: test.sample
+ :filename: ../test/sample.py
:func: parser
:prog: sample
- :path: game
\ No newline at end of file
+ :path: game
diff --git a/docs/usage.rst b/docs/usage.rst
index d27dcc4..bf6ad73 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -1,29 +1,26 @@
-
-
-
Basic usage
------------------
+===========
-Extension adds "argparse" directive::
+This extension adds the "argparse" directive::
.. argparse::
:module: my.module
:func: my_func_that_returns_a_parser
:prog: fancytool
-`module`, `func` and `prog` options are required.
+The `module`, `func` and `prog` options are required.
-func is function that returns an instance of the `argparse.ArgumentParser` class.
+`func` is a function that returns an instance of the `argparse.ArgumentParser` class.
-Alternative syntax is to use :ref: like this::
+Alternatively, one can use :ref: like this::
.. argparse::
:ref: my.module.my_func_that_returns_a_parser
:prog: fancytool
-in this case :ref: also may point directly to argument parser instance.
+In this case :ref: points directly to argument parser instance.
-For this directive to work, you should point it to the function, that will return pre-filled `ArgumentParser`.
+For this directive to work, you should point it to the function that will return a pre-filled `ArgumentParser`.
Something like::
def my_func_that_return_parser():
@@ -40,7 +37,17 @@ Something like::
return parser
.. note::
- We will use this example as a reference for every example in this doc.
+ We will use this example as a reference for every example in this document.
+
+To document a file that is not part of a module, use :filename::
+
+ .. argparse::
+ :filename: script.py
+ :func: my_func_that_returns_a_parser
+ :prog: script.py
+
+The 'filename' option could be absolute path or a relative path under current
+working dir.
\:module\:
Module name, where the function is located
@@ -48,14 +55,19 @@ Something like::
\:func\:
Function name
+\:ref\:
+ A combination of :module: and :func:
+
+\:filename\:
+ A file name, in cases where the file to be documented is not part of a module.
+
\:prog\:
- It's just name of your tool (or how it's should appear in your documentation). Ex. if you run your script as
+ The name of your tool (or how it should appear in the documentation). For example, if you run your script as
`./boo --some args` then \:prog\: will be "boo"
-That's it. Directive will render positional arguments, options and sub-commands.
-
-Sub-commands are limited to one level. But, you always can output help for subcommands separately::
+That's it. Directives will render positional arguments, options and sub-commands.
+Sub-commands are limited to one level. But, you can always output help for subcommands separately::
.. argparse::
:module: my.module
@@ -65,7 +77,7 @@ Sub-commands are limited to one level. But, you always can output help for subco
This will render same doc for "install" subcommand.
-Nesting level is not limited::
+Nesting level is unlimited::
.. argparse::
:module: my.module
@@ -75,6 +87,14 @@ Nesting level is not limited::
Other useful directives
------------------------------------------
+-----------------------
+
+:nodefault: Do not show any default values.
+
+:nodefaultconst: Like nodefault:, except it applies only to arguments of types `store_const`, `store_true` and `store_false`.
+
+:nosubcommands: Do not show subcommands.
+
+:noepilogue: Do not parse the epilogue, which can be useful if it contains text that could be incorrectly parse as reStructuredText.
-:nodefault: will hide all default values of options.
+:nodescription: Do not parse the description, which can be useful if it contains text that could be incorrectly parse as reStructuredText.
diff --git a/requirements.txt b/requirements.txt
deleted file mode 100644
index e69de29..0000000
diff --git a/requirements_dev.txt b/requirements_dev.txt
index 68e82ea..3c017e8 100644
--- a/requirements_dev.txt
+++ b/requirements_dev.txt
@@ -1,3 +1,4 @@
pytest
sphinx_rtd_theme
sphinx
+CommonMark>=0.5.6
diff --git a/requirements_rtd.txt b/requirements_rtd.txt
new file mode 100644
index 0000000..2d43d1b
--- /dev/null
+++ b/requirements_rtd.txt
@@ -0,0 +1,3 @@
+pytest
+sphinx
+CommonMark>=0.5.6
diff --git a/setup.py b/setup.py
index 4dd289f..c103998 100644
--- a/setup.py
+++ b/setup.py
@@ -1,28 +1,31 @@
-import sys
from setuptools import setup
-# from tests import PyTest
-deps = ["sphinx"]
-if sys.version_info[:2] == (2, 6):
- deps.append('argparse')
+def getVersion():
+ f = open("sphinxarg/__init__.py")
+ _ = f.read()
+ ver = _.split("'")[1]
+ f.close()
+ return ver
+
setup(
name='sphinx-argparse',
- version='0.1.15',
+ version=getVersion(),
packages=[
'sphinxarg',
],
-
url='',
license='MIT',
- author='Aleksandr Rudakov',
+ author='Aleksandr Rudakov and Devon Ryan',
author_email='ribozz at gmail.com',
- description='Sphinx extension that automatically document argparse commands and options',
+ description='Sphinx extension that automatically documents argparse commands and options',
long_description='',
- install_requires=deps,
-
+ install_requires=[
+ 'sphinx',
+ 'CommonMark>=0.5.6'
+ ],
extras_require={
- 'dev': ['pytest', 'sphinx_rtd_theme', 'sphinx'],
+ 'dev': ['pytest', 'sphinx_rtd_theme']
}
)
diff --git a/sphinxarg/__init__.py b/sphinxarg/__init__.py
index e69de29..fc79d63 100644
--- a/sphinxarg/__init__.py
+++ b/sphinxarg/__init__.py
@@ -0,0 +1 @@
+__version__ = '0.2.1'
diff --git a/sphinxarg/ext.py b/sphinxarg/ext.py
index 6b7fc4d..39a70cf 100644
--- a/sphinxarg/ext.py
+++ b/sphinxarg/ext.py
@@ -4,10 +4,13 @@ import os
from docutils import nodes
from docutils.statemachine import StringList
from docutils.parsers.rst.directives import flag, unchanged
-from sphinx.util.compat import Directive
+from docutils.parsers.rst import Parser, Directive
+from docutils.utils import new_document
+from docutils.frontend import OptionParser
from sphinx.util.nodes import nested_parse_with_titles
from sphinxarg.parser import parse_parser, parser_navigate
+from sphinxarg.markdown import parseMarkDownBlock
def map_nested_definitions(nested_content):
@@ -34,129 +37,205 @@ def map_nested_definitions(nested_content):
raise Exception('Unknown classifier: %s' % classifier)
idx = subitem.first_child_matching_class(nodes.term)
if idx is not None:
- ch = subitem[idx]
- if len(ch.children) > 0:
- term = ch.children[0].astext()
+ term = subitem[idx]
+ if len(term.children) > 0:
+ term = term.children[0].astext()
idx = subitem.first_child_matching_class(nodes.definition)
if idx is not None:
- def_node = subitem[idx]
- def_node.attributes['classifier'] = classifier
- definitions[term] = def_node
+ subContent = []
+ for _ in subitem[idx]:
+ if isinstance(_, nodes.definition_list):
+ subContent.append(_)
+ definitions[term] = (classifier, subitem[idx].astext(), subContent)
+
return definitions
-def print_arg_list(data, nested_content):
- definitions = map_nested_definitions(nested_content)
- items = []
- if 'args' in data:
- for arg in data['args']:
- my_def = [nodes.paragraph(text=arg['help'])] if arg['help'] else []
- name = arg['name']
- my_def = apply_definition(definitions, my_def, name)
- if len(my_def) == 0:
- my_def.append(nodes.paragraph(text='Undocumented'))
- if 'choices' in arg:
- my_def.append(nodes.paragraph(
- text=('Possible choices: %s' % ', '.join([str(c) for c in arg['choices']]))))
- items.append(
- nodes.option_list_item(
- '', nodes.option_group('', nodes.option_string(text=name)),
- nodes.description('', *my_def)))
- return nodes.option_list('', *items) if items else None
+def renderList(l, markDownHelp):
+ """
+ Given a list of reStructuredText or MarkDown sections, return a docutils node list
+ """
+ if len(l) == 0:
+ return []
+ if markDownHelp:
+ return parseMarkDownBlock('\n\n'.join(l) + '\n')
+ else:
+ settings = OptionParser(components=(Parser,)).get_default_values()
+ document = new_document(None, settings)
+ Parser().parse('\n\n'.join(l) + '\n', document)
+ return document.children
-def print_opt_list(data, nested_content):
+def print_action_groups(data, nested_content, markDownHelp=False):
+ """
+ Process all 'action groups', which are also include 'Options' and 'Required
+ arguments'. A list of nodes is returned.
+ """
definitions = map_nested_definitions(nested_content)
- items = []
- if 'options' in data:
- for opt in data['options']:
- names = []
... 1473 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/sphinx-argparse.git
More information about the Python-modules-commits
mailing list