Commit 72f60cad authored by ChangZhuo Chen's avatar ChangZhuo Chen

Import sphinx-argparse_0.2.1.orig.tar.gz

parent 2942075e
......@@ -37,3 +37,4 @@ nosetests.xml
.env/
docs/_build/
.cache/
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@gmail.com
\ No newline at end of file
- py.test
- flake8 . --ignore=E501 --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)
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
......@@ -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'),
]
......
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
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.
`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)
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']
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:
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.
==============
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
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.
pytest
sphinx_rtd_theme
sphinx
CommonMark>=0.5.6
pytest
sphinx
CommonMark>=0.5.6
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@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,