Skip to content

Commit

Permalink
Several improvements + Read The docs modern theme
Browse files Browse the repository at this point in the history
  • Loading branch information
Aleksandr Rudakov committed May 15, 2014
1 parent c8bc98e commit 39eaf66
Show file tree
Hide file tree
Showing 14 changed files with 432 additions and 243 deletions.
8 changes: 8 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,14 @@ http://sphinx-argparse.readthedocs.org/en/latest/

Changelog:

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

Expand Down
10 changes: 8 additions & 2 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@
# If extensions (or extra_modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
import sphinx_rtd_theme

sys.path.insert(0, os.path.abspath('..'))

# -- General configuration -----------------------------------------------------
Expand All @@ -25,7 +27,11 @@

# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode']
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', 'sphinxarg.ext']

html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]


# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Expand Down Expand Up @@ -94,7 +100,7 @@

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
#html_theme = 'default'

# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
Expand Down
23 changes: 23 additions & 0 deletions docs/contrib.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@



Contribution
-----------------------------------------

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.

https://github.com/ribozz/sphinx-argparse

Don't forget to run tests before commit::

py.test`

Any feedback is welcome: ribozz (a) gmail dot com
76 changes: 76 additions & 0 deletions docs/extend.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@




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

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

Also any valid markup...
*************************

... may `be` *applied* here

including::

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

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

foo
This text will go right after "foo" positional argument help.

install
This text will go right after "install" subcommand help and before it's arguments.

--upgrade
This text will go to upgrade option of install subcommand, nesting is not limited


You can also add classifiers to definition-list that will change behavior of content merge algorythm::

.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool

My content that will be inserted as extra, right before argument list.

foo : @before
This text will go right after "foo" positional argument help.

install : @replace
This text will go right after "install" subcommand help and befor it's arguments.

--upgrade : @after
This text will go to upgrade option of install subcommand, nesting is not limited


@before
Insert content before parsed help message of argument/option/subcommand.

@after
Insert content after parsed help message of argument/option/subcommand.

This is default, if you do not specify classifier explicitly.

@replace
Replace content of help message of argument/option/subcommand.
233 changes: 7 additions & 226 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,234 +5,15 @@
for command line tools based on argparse library.


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).
.. toctree::
:maxdepth: 2

Package is available in the Python Package Index::
install
usage
extend
sample
contrib

pip install sphinx-argparse

Enable extension in your sphinx config::

extensions += ['sphinxarg.ext']

Basic usage
-----------------

Extension adds "argparse" directive::

.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool

`module`, `func` and `prog` options are required.

For this directive to work, you should point it to the function, that will return pre-filled `ArgumentParser`.
Something like::

def my_func_that_return_parser():
parser = argparse.ArgumentParser()
parser.add_argument('foo', default=False, help='foo help')
parser.add_argument('bar', default=False)

subparsers = parser.add_subparsers()

subparser = subparsers.add_parser('install', help='install help')
subparser.add_argument('ref', type=str, help='foo1 help')
subparser.add_argument('--upgrade', action='store_true', default=False, help='foo2 help')

return parser

.. note::
We will use this example as a reference for every example in this doc.

\:module\:
Module name, where the function is located

\:func\:
Function name

\:prog\:
It's just name of your tool (or how it's should appear in your documentation). Ex. 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::


.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
:path: install

This will render same doc for "install" subcommand.

Nesting level is not limited::

.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
:path: install subcomand1 subcommand2 subcommand3


Other useful directives
-----------------------------------------

:nodefault: will hide all default values of options.


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

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

Also any valid markup...
*************************

... may `be` *applied* here

including::

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

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

foo
This text will go right after "foo" positional argument help.

install
This text will go right after "install" subcommand help and before it's arguments.

--upgrade
This text will go to upgrade option of install subcommand, nesting is not limited


You can also add classifiers to definition-list that will change behavior of content merge algorythm::

.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool

My content that will be inserted as extra, right before argument list.

foo : @before
This text will go right after "foo" positional argument help.

install : @replace
This text will go right after "install" subcommand help and befor it's arguments.

--upgrade : @after
This text will go to upgrade option of install subcommand, nesting is not limited


@before
Insert content before parsed help message of argument/option/subcommand.

@after
Insert content after parsed help message of argument/option/subcommand.

This is default, if you do not specify classifier explicitly.

@replace
Replace content of help message of argument/option/subcommand.


Example structure of pages
-----------------------------------------

Here is example structure of documentation for complex commands with lots of subcommands.
You are free to use any structure, but this may be a good starting point.

File "index.rst"::

.. toctree::
:maxdepth: 2

cmd

File "cmd.rst"::


Command line utitlites
***********************

.. toctree::
:maxdepth: 1

cmd_main
cmd_subcommand


File "cmd_main.rst"::


Fancytool command
***********************

.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool

subcommand
Here we add reference to subcommand, to simplify navigation.
See :doc:`cmd_subcommand`


File "cmd_subcommand.rst"::

Subcommand command
***********************

.. argparse::
:module: my.module
:func: my_func_that_return_parser
:prog: fancytool
:path: subcommand


Contribution
-----------------------------------------

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.

https://github.com/ribozz/sphinx-argparse

Don't forget to run tests before commit::

py.test`

Any feedback is welcome: ribozz (a) gmail dot com
Loading

0 comments on commit 39eaf66

Please sign in to comment.