Commit 2bc6804e authored by Dmitry Shachnev's avatar Dmitry Shachnev

Update upstream source from tag 'upstream/0.2.2'

Update to upstream version '0.2.2'
with Debian dir 58074d79a32231280f86c36144e6bb7dda888cf4
parents 5aeba482 3c1a3541
......@@ -11,4 +11,4 @@ install:
script:
- py.test
- flake8 . --ignore=E501 --exclude=docs/conf.py
- flake8 . --ignore=E501,E722,E741 --exclude=docs/conf.py
[![Build Status](https://travis-ci.org/ribozz/sphinx-argparse.svg?branch=master)](https://travis-ci.org/ribozz/sphinx-argparse) [![Documentation Status](https://readthedocs.org/projects/sphinx-argparse/badge/?version=stable)](http://sphinx-argparse.readthedocs.org/) [![PyPI version](https://badge.fury.io/py/sphinx-argparse.svg)](https://badge.fury.io/py/sphinx-argparse) [Install with conda](https://anaconda.org/conda-forge/sphinx-argparse/badges/installer/conda.svg) [Conda downloads](https://anaconda.org/conda-forge/sphinx-argparse/badges/downloads.svg)
[![Build Status](https://travis-ci.org/ribozz/sphinx-argparse.svg?branch=master)](https://travis-ci.org/ribozz/sphinx-argparse)
[![Documentation Status](https://readthedocs.org/projects/sphinx-argparse/badge/?version=stable)](http://sphinx-argparse.readthedocs.org/)
[![PyPI version](https://badge.fury.io/py/sphinx-argparse.svg)](https://badge.fury.io/py/sphinx-argparse)
[![Install with conda](https://anaconda.org/conda-forge/sphinx-argparse/badges/installer/conda.svg)](https://github.com/conda-forge/sphinx-argparse-feedstock)
![Conda downloads](https://anaconda.org/conda-forge/sphinx-argparse/badges/downloads.svg)
sphinx-argparse
===============
A sphinx extension that automatically documents argparse commands and options.
For installation and usage details see the [documentation](http://sphinx-argparse.readthedocs.org/en/latest/).
Changelog & contributors
========================
0.2.1
-----
* Stopped importing `sphinx.util.compat`, which was causing issues like that seen in [#65](https://github.com/ribozz/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.
- 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)
- Support for subcommand descriptions #24 (Campbell Barton)
- Improved parsing of content of `epilog` and `description` #25 (Louis - https://github.com/paternal)
- 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
For installation and usage details see the [documentation](http://sphinx-argparse.readthedocs.org/en/latest/). The changelog is also [found there](http://sphinx-argparse.readthedocs.org/en/latest/changelog.html).
**********
Change log
**********
0.2.2
#####
* CommonMark is now only imported if absolutely required. This should fix failures on read the docs. Thanks to @Chilipp for fixing this!
0.2.1
#####
* Stopped importing `sphinx.util.compat`, which was causing issues like that seen in `#65 <https://github.com/ribozz/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/ribozz/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/ribozz/sphinx-argparse/issues/58>`_.
* Fixed quoting of default strings (issue `#59 <https://github.com/ribozz/sphinx-argparse/issues/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 <https://github.com/ribozz/sphinx-argparse/issues/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)
* Support for subcommand descriptions #24 (Campbell Barton)
* Improved parsing of content of `epilog` and `description` #25 (Louis - https://github.com/paternal)
* 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 accident.
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
......@@ -20,7 +20,7 @@ You can add extra content or even replace some parts of the documentation genera
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 targetted (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).::
.. argparse::
:module: my.module
......
......@@ -14,6 +14,7 @@
sample
misc
markdown
changelog
contrib
......
pytest
sphinx_rtd_theme
sphinx
sphinx>=1.2.0
CommonMark>=0.5.6
pytest
sphinx
sphinx>=1.2.0
CommonMark>=0.5.6
......@@ -15,17 +15,32 @@ setup(
packages=[
'sphinxarg',
],
url='',
url='https://github.com/ribozz/sphinx-argparse',
license='MIT',
author='Aleksandr Rudakov and Devon Ryan',
author_email='ribozz@gmail.com',
description='Sphinx extension that automatically documents argparse commands and options',
long_description='',
description='A sphinx extension that automatically documents argparse commands and options',
long_description="""A sphinx extension that automatically documents argparse commands and options.
For installation and usage details, see the `documentation <http://sphinx-argparse.readthedocs.org/en/latest/>`_.""",
classifiers=[
'Development Status :: 5 - Production/Stable',
'Intended Audience :: Developers',
'License :: OSI Approved :: MIT License',
'Programming Language :: Python :: 2.7',
'Programming Language :: Python :: 3.2',
'Programming Language :: Python :: 3.3',
'Programming Language :: Python :: 3.4',
'Programming Language :: Python :: 3.5',
'Programming Language :: Python :: 3.6',
'Topic :: Documentation :: Sphinx',
'Topic :: Software Development :: Documentation'
],
install_requires=[
'sphinx',
'CommonMark>=0.5.6'
'sphinx>=1.2.0'
],
extras_require={
'dev': ['pytest', 'sphinx_rtd_theme']
'dev': ['pytest', 'sphinx_rtd_theme'],
'markdown': ['CommonMark>=0.5.6']
}
)
__version__ = '0.2.1'
__version__ = '0.2.2'
......@@ -10,7 +10,6 @@ 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):
......@@ -51,22 +50,24 @@ def map_nested_definitions(nested_content):
return definitions
def renderList(l, markDownHelp):
def renderList(l, markDownHelp, settings=None):
"""
Given a list of reStructuredText or MarkDown sections, return a docutils node list
"""
if len(l) == 0:
return []
if markDownHelp:
from sphinxarg.markdown import parseMarkDownBlock
return parseMarkDownBlock('\n\n'.join(l) + '\n')
else:
settings = OptionParser(components=(Parser,)).get_default_values()
if settings is None:
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_action_groups(data, nested_content, markDownHelp=False):
def print_action_groups(data, nested_content, markDownHelp=False, settings=None):
"""
Process all 'action groups', which are also include 'Options' and 'Required
arguments'. A list of nodes is returned.
......@@ -141,7 +142,7 @@ def print_action_groups(data, nested_content, markDownHelp=False):
n = nodes.option_list_item('',
nodes.option_group('', nodes.option_string(text=term)),
nodes.description('', *renderList(desc, markDownHelp)))
nodes.description('', *renderList(desc, markDownHelp, settings)))
items.append(n)
section += nodes.option_list('', *items)
......@@ -150,7 +151,7 @@ def print_action_groups(data, nested_content, markDownHelp=False):
return nodes_list
def print_subcommands(data, nested_content, markDownHelp=False):
def print_subcommands(data, nested_content, markDownHelp=False, settings=None):
"""
Each subcommand is a dictionary with the following keys:
......@@ -191,10 +192,12 @@ def print_subcommands(data, nested_content, markDownHelp=False):
for element in renderList(desc, markDownHelp):
sec += element
sec += nodes.literal_block(text=child['bare_usage'])
for x in print_action_groups(child, nested_content + subContent, markDownHelp):
for x in print_action_groups(child, nested_content + subContent, markDownHelp,
settings=settings):
sec += x
for x in print_subcommands(child, nested_content + subContent, markDownHelp):
for x in print_subcommands(child, nested_content + subContent, markDownHelp,
settings=settings):
sec += x
subCommands += sec
......@@ -456,6 +459,7 @@ class ArgParseDirective(Directive):
items = []
nested_content = nodes.paragraph()
if 'markdown' in self.options:
from sphinxarg.markdown import parseMarkDownBlock
items.extend(parseMarkDownBlock('\n'.join(self.content) + '\n'))
else:
self.state.nested_parse(
......@@ -475,9 +479,11 @@ class ArgParseDirective(Directive):
else:
items.append(self._nested_parse_paragraph(result['description']))
items.append(nodes.literal_block(text=result['usage']))
items.extend(print_action_groups(result, nested_content, markDownHelp))
items.extend(print_action_groups(result, nested_content, markDownHelp,
settings=self.state.document.settings))
if 'nosubcommands' not in self.options:
items.extend(print_subcommands(result, nested_content, markDownHelp))
items.extend(print_subcommands(result, nested_content, markDownHelp,
settings=self.state.document.settings))
if 'epilog' in result and 'noepilog' not in self.options:
items.append(self._nested_parse_paragraph(result['epilog']))
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment