alex-rudakov / sphinx-argparse Goto Github PK

I cannot find manpage sections listed in the source code at _construct_manpage_specific_structure() in the generated manpage. Am I missing some configuration by any chance?

The generated manpage has those sections:

NAME
POSITIONAL ARGUMENTS
NAMED ARGUMENTS
AUTHOR
COPYRIGHT

While from the source code and usual best practices in manpage generation I was expecting to have:

• a SYNOPSIS section with the synopsis of the command
• a DESCRIPTION section with the description taken from the argparse parser
• an OPTION section with what is now in the NAMED ARGUMENTS and maybe POSITIONAL ARGUMENTS too? I'm not sure if usually the positional arguments are documented inside the DESCRIPTION section.

I'm not familiar with docutils library, so I'm not sure if those were meant to be subtitles inside the section, but the final results doesn't seems to follow best practices and the docstring in the code.

Versions used:

Sphinx==1.6.4
sphinx-argparse==0.2.1
docutils==0.14
``

Epilog just gets ignored. Would be nice if it would be shown as it might contain examples.

sphinx-argparse says here that it allows extended directives for arguments.

I can add these extended directives, but when I do so any reStructuredText formatting is stripped away from the directives.

See this issue for more details.

sphinx.util.compat is deprecated and although latest sphinx-1.6.2 doesn't import it anymore internally, it causes issues with rc releases of docutils when sphinx.util.compat is imported by extensions, like:

Running Sphinx v1.6.2
making output directory...
Exception occurred:
  File "/home/travis/virtualenv/python3.4.2/lib/python3.4/site-packages/sphinx/util/compat.py", line 21, in <genexpr>
    docutils_version = tuple(int(x) for x in _du_version.split('.')[:2])
ValueError: invalid literal for int() with base 10: '14rc1'

Error log:

# Sphinx version: 1.6.2
# Python version: 3.5.3 (CPython)
# Docutils version: 0.14rc1 prerelease
# Jinja2 version: 2.9.6
# Last messages:

# Loaded extensions:
Traceback (most recent call last):
  File "c:\users\zimmermann\miniconda3\envs\coala\lib\site-packages\sphinx\cmdline.py", line 305, in main
    opts.warningiserror, opts.tags, opts.verbosity, opts.jobs)
  File "c:\users\zimmermann\miniconda3\envs\coala\lib\site-packages\sphinx\application.py", line 196, in __init__
    self.setup_extension(extension)
  File "c:\users\zimmermann\miniconda3\envs\coala\lib\site-packages\sphinx\application.py", line 456, in setup_extension
    self.registry.load_extension(self, extname)
  File "c:\users\zimmermann\miniconda3\envs\coala\lib\site-packages\sphinx\registry.py", line 196, in load_extension
    mod = __import__(extname, None, None, ['setup'])
  File "c:\users\zimmermann\miniconda3\envs\coala\lib\site-packages\sphinxarg\ext.py", line 10, in <module>
    from sphinx.util.compat import Directive
  File "c:\users\zimmermann\miniconda3\envs\coala\lib\site-packages\sphinx\util\compat.py", line 21, in <module>
    docutils_version = tuple(int(x) for x in _du_version.split('.')[:2])
  File "c:\users\zimmermann\miniconda3\envs\coala\lib\site-packages\sphinx\util\compat.py", line 21, in <genexpr>
    docutils_version = tuple(int(x) for x in _du_version.split('.')[:2])
ValueError: invalid literal for int() with base 10: '14rc1'

Then you have to add workarounds to conf.py like in coala/coala#4334

You can also read more about the deprecation here:

sphinx-doc/sphinx#3846 (comment)

cc @jfbu @tk0miya @jayvdb

lsf = drivers_parser.add_parser('lsf', help='Flock your jobs to lsf', usage=baseUsageStr.format('lsf'), formatter_class=lambda prog: CustomFormatter(prog, max_help_position=30))
lsf.add_argument('--optLSFConf', metavar='', type=str, required=False, default='-q short')
lsf.add_argument('--optLSFNFilesPerJob', metavar='', type=int, required=False, default=1)

As you can see, it looks like it suggests people should write --optLSFConf=-q short instead of --optLSFConf="-q short".

I'm documenting a program with sub-commands. I use both help="short message" and description="Longer message..." options to add_parser(), which produces a nice summary when using the -h flag on the main command, and longer messages when using -h on sub-commands.

I note these problems:

1. The generated documentation includes both of these strings, which is redundant. If the description is given, the help should probably not be displayed.
2. The @replace directive currently replaces only the help text; the description is still shown.
3. The @after directive places the given text after the help text, but before the description text.

Currently I see no way to display both the command-line help messages I want at run time and the documentation I want via sphinx-argparse.

Thanks!

In basic usage the noepilog option is spelled noepilogue which is wrong in respect to the corresponding code.

I've just downgraded to 0.1.17 and confirmed that my sphinx pages are broken by something between commit 4dd6b91 (merge branch 'release/0.1.17') and 0.2.0. (The issue I reported yesterday also was introduced between these commits.)

I'm using the "@replace" directive with code blocks such as:

  .. code-block:: bash

     $ gt config project
     [MyProject]
     GCAM.DefaultProject = MyProject
     GCAM.ProjectRoot = /Users/rjp/bitbucket/myProject
     GCAM.ProjectXmlFile = /Users/rjp/bitbucket/myProject/etc/project.xml

     $ gt config -x GCAM.DefaultProject
     MyProject

These render properly in 0.1.17, but render as plain text in 0.2.0, with all the lines in each "paragraph" concatenated.

If you want to see my doc pages as an example of a script with extensive sub-commands, do "pip install pygcam" and build the docs. The "gcamtool.html" page lists all the subcommands; an example with proper formatting: http://pygcam.readthedocs.io/en/latest/gcamtool.html

I have a version argument added with following code:

 parser.add_argument('-V', '--version', action='version', version=program_version_message)

It renders as:

-V===SUPPRESS==, --version===SUPPRESS==

I would expect it to be just:

-V, --version

I want to include a multi-paragraph description for my program. With argparse, I can do that using formatter_class=RawDescriptionHelpFormatter. sphinx-argparse always uses the default formatter class, which removes all extra whitespace.

File "/usr/local/lib/python3.4/dist-packages/sphinxarg/ext.py", line 212
    print attr_name

It fails on my Python 3 Sphinx. Cannot you fix it?

Add passparser to the documentation somewhere please. Right now it's only referenced in the changelog.

Hi,
First of all, thanks for the great extension! It's been very useful.

Just one small bug I noticed, which can be seen in your examples page:
https://sphinx-argparse.readthedocs.io/en/stable/sample.html

For example, in the sample commands, the --tree option is rendered as it is on the command-line helper, but in the Named Arguments section, it is rendered as –tree, with an en dash instead of the double hyphen. It happens the same for all these cases.

Do you have any clue about it? Thanks!

(cc @alejandrovr)

Related to #44, the following still need to be finalized:

• Can you make images links?
• Can code blocks be assigned a code type?
• Is there a way to get sphinx to not strip white-space from the right?

Additionally, it would be nice to render reStructuredText and Markdown in command descriptions and help messages:

• reStructuredText
• Markdown

This would require an additional directive option (:renderHelp: reStructuredText or :renderHelp:Markdown maybe).

In the HTML output some long options are wrapped exactly at the double dash, making quite hard to read the table. As an example I got:

-c, --
config

I'm using the Read the Docs theme and I've applied the CSS fix for white-space as suggested.
Have you considered the possibility to replace those specific dashes with non-breaking ones (‑) ?

Versions:

docutils==0.14
Sphinx==1.6.4
sphinx-argparse==0.2.1
sphinx-rtd-theme==0.2.4

https://pythonhosted.org/sphinxcontrib-autoprogram/

Given that this isn't widely available currently, this would make it easier for me to package for internal use at work.

See http://api.coala.io/en/latest/Developers/coala_settings.html would be nice to have "Options", "Positional Arguments" etc. headers so they're linkable and give the document some structure

I want to update sphinx-argparse to be able to use :nodescription:.

However, when I update the package I get something like this:

is there a way to get rid of these arguments, and keep it as it was before?

Like here https://rna-pdb-tools.readthedocs.io/en/latest/utils.html#cluster

BTW Thanks for this great tool!

When the :func: argument is incorrect the output does not indicate where the failure is. Here is a sample log:

File "C:\Python27\lib\site-packages\sphinxarg\ext.py", line 199, in run
func = getattr(mod, self.options['func'])
AttributeError: 'module' object has no attribute 'ProcessArgs'

I have a fix for this I will push soon.

When a subcommand has an alias set, it will have its documentation written for the original command and for every alias.

This is very easy to redo, see the example using alias in Python docs. - If you add multiple, you can easily see the problem.
https://docs.python.org/3/library/argparse.html#sub-commands

If the name of a positional argument is long, the table gets rendered incorrectly:

Using sphinx-argparse 0.2.2 with Sphinx 1.7.2 on Python 2.7.5

Arguments (both required and optional) with empty string as default value are rendered like this:

Equal sign without anything after is confusing, would be better the leave out = or to show python empty string, like name=''.
Adding a new directive :showemptydefault: would be nice, so that empty defaults are shown only if the directive is given.

Version: sphinx-argparse==0.1.17

In the generated output I see required named arguments, eg

parser.add_argument('--foo', required=True)

being grouped under the heading "optional arguments". This is likely to be very confusing for my application's users. The usage text is correct (ie. omits square brackets).

I would like the nosubcommands option to be available for normal argparse usage and not just when generating manpages.

I have implemented this change on a local copy and would be fine contributing it. I have never contributed before so would just need to know the procedure. I have created a pull request for this change, so the issue can be closed.

The options table isn't very well readable :/ See http://api.coala.io/en/latest/Developers/coala_settings.html

In the HTML output when there are both short and long versions of an option (e.g. -v and --verbose) the dashes in front of both options look the same. There should be a clear double dash in front of the long option name.

An rst file that demonstrates the bug is:

Notice there is no visual difference between single dash ``-`` and double-dash ``--``, and the ``-h`` option isn't listed under options.

.. argparse::
    :module: parser_bug
    :func: construct_parser
    :prog: python parser_bug.py

where the file parser_bug.py is:

def construct_parser():

    import argparse

    parser = argparse.ArgumentParser()
    parser.formatter_class = argparse.RawDescriptionHelpFormatter
    parser.add_argument('-v', '--verbose', help="More information while running",
                        action='store_true')

    return parser

if __name__ == '__main__':
    parser = construct_parser()
    parser.parse_args()

A question not an issue: Any thoughts on a path to moving toward including this in sphinx-apidoc. I had a quick look at the apidoc script and it seems it might make sense to do something similar ... might be tricky to handle generic cases though.

Or maybe this already exists and I have not found it?

When adding a subgroup like the following (notice that title is missing):

parser.add_argument_group(description='foo')

the process will crash with the error below. According to the Python docs, the default for title is None. This can be fixed by passing in a title to add_argument_group.

Traceback (most recent call last):
  File "/home/users/malbert/work/nestea/env/lib/python3.5/site-packages/sphinx/cmdline.py", line 306, in main
    app.build(opts.force_all, filenames)
  File "/home/users/malbert/work/nestea/env/lib/python3.5/site-packages/sphinx/application.py", line 339, in build
    self.builder.build_update()
  File "/home/users/malbert/work/nestea/env/lib/python3.5/site-packages/sphinx/builders/__init__.py", line 331, in build_update
    'out of date' % len(to_build))
  File "/home/users/malbert/work/nestea/env/lib/python3.5/site-packages/sphinx/builders/__init__.py", line 344, in build
    updated_docnames = set(self.env.update(self.config, self.srcdir, self.doctreedir))
  File "/home/users/malbert/work/nestea/env/lib/python3.5/site-packages/sphinx/environment/__init__.py", line 583, in update
    self._read_serial(docnames, self.app)
  File "/home/users/malbert/work/nestea/env/lib/python3.5/site-packages/sphinx/environment/__init__.py", line 602, in _read_serial
    self.read_doc(docname, app)
  File "/home/users/malbert/work/nestea/env/lib/python3.5/site-packages/sphinx/environment/__init__.py", line 732, in read_doc
    app.emit('doctree-read', doctree)
  File "/home/users/malbert/work/nestea/env/lib/python3.5/site-packages/sphinx/application.py", line 489, in emit
    return self.events.emit(event, self, *args)
  File "/home/users/malbert/work/nestea/env/lib/python3.5/site-packages/sphinx/events.py", line 79, in emit
    results.append(callback(*args))
  File "/home/users/malbert/work/nestea/env/lib/python3.5/site-packages/sphinx/environment/collectors/toctree.py", line 127, in process_doc
    toc = build_toc(doctree)
  File "/home/users/malbert/work/nestea/env/lib/python3.5/site-packages/sphinx/environment/collectors/toctree.py", line 121, in build_toc
    sub_item = build_toc(sectionnode, depth + 1)
  File "/home/users/malbert/work/nestea/env/lib/python3.5/site-packages/sphinx/environment/collectors/toctree.py", line 121, in build_toc
    sub_item = build_toc(sectionnode, depth + 1)
  File "/home/users/malbert/work/nestea/env/lib/python3.5/site-packages/sphinx/environment/collectors/toctree.py", line 112, in build_toc
    anchorname = '#' + sectionnode['ids'][0]
TypeError: Can't convert 'NoneType' object to str implicitly

I have an argparse epilogue that contains text that can be interpreted as .rst. In order to allow the documentation to be generated properly, I need to the epilogue when parsing.

For consistency, the option to ignore the description can also be added if desired.

I have implemented this change on a local copy and would be fine contributing it. I have never contributed before so would just need to know the procedure. I have created a pull request for this change, so the issue can be closed.

When a named argument requires a value, the value label is not included into the generated documentation (I've checked in both HTML and manpage), making impossible to know if they need an argument or not.

As an example, if in the normal help message I have:

--foo         set the foo option
--bar VALUE   set the bar option to VALUE

I would expect the VALUE to be kept into the documentation, but it's not as far as I can tell.

Version used:

Sphinx==1.6.4
sphinx-argparse==0.2.1
``

We don't really wanna use rst for our main description, rather markdown which is optimized for plain text readability.

Would be nice to auto convert it to rst, see also http://api.coala.io/en/latest/Developers/coala_settings.html - maybe using pandoc or somethin'

Mock imports are currently not supported. It would be great if sphinx-argparse would use the autodoc_mock_imports list provided in conf.py.

Recently RTD just stopped building my docs with the following error:

python /home/docs/checkouts/readthedocs.org/user_builds/fyrd/envs/dev/bin/sphinx-build -T -E -b readthedocs -d _build/doctrees-readthedocs -D language=en . _build/html

Running Sphinx v1.5.3
making output directory...

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/fyrd/envs/dev/lib/python3.5/site-packages/sphinx/application.py", line 512, in setup_extension
    mod = __import__(extension, None, None, ['setup'])
  File "/home/docs/checkouts/readthedocs.org/user_builds/fyrd/envs/dev/lib/python3.5/site-packages/sphinxarg/ext.py", line 13, in <module>
    from sphinxarg.markdown import parseMarkDownBlock
  File "/home/docs/checkouts/readthedocs.org/user_builds/fyrd/envs/dev/lib/python3.5/site-packages/sphinxarg/markdown.py", line 1, in <module>
    from CommonMark import Parser  # >= 0.5.6
ImportError: cannot import name 'Parser'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/fyrd/envs/dev/lib/python3.5/site-packages/sphinx/cmdline.py", line 295, in main
    opts.warningiserror, opts.tags, opts.verbosity, opts.jobs)
  File "/home/docs/checkouts/readthedocs.org/user_builds/fyrd/envs/dev/lib/python3.5/site-packages/sphinx/application.py", line 199, in __init__
    self.setup_extension(extension)
  File "/home/docs/checkouts/readthedocs.org/user_builds/fyrd/envs/dev/lib/python3.5/site-packages/sphinx/application.py", line 516, in setup_extension
    err)
sphinx.errors.ExtensionError: Could not import extension sphinxarg.ext (exception: cannot import name 'Parser')

Extension error:
Could not import extension sphinxarg.ext (exception: cannot import name 'Parser')

I also reported the on the RTD issue tracker here: readthedocs/readthedocs.org#3032

My generated usage text is way too long, so it generates a very narrow scrolling window in order view it all.

It would be awesome if there was a way to insert line breaks in the usage to make it look prettier.

I have a set of parsers added to a subparser. For some reason the "description" field of each subparser is being displayed below an "Undocumented" string.

It appears this could be fixed by removing a line of code in ext.py, but I am concerned about side effects.

This parser

def create_parser2():
    parser = argparse.ArgumentParser('foo')
    parser.add_argument('--foo', help='foo help')
    grp1 = parser.add_argument_group('bar options')
    grp1.add_argument('--bar', help='bar help')
    grp2 = parser.add_argument_group('bla options')
    grp2.add_argument('--bla', help='bla help')
    return parser

gives this command line help:

optional arguments:
  -h, --help  show this help message and exit
  --foo FOO   foo help

bar options:
  --bar BAR   bar help

bla options:
  --bla BLA   bla help

but renders to following sphinx output:

.. argparse::
  :module: foo
  :func: create_parser2
  :prog: foo
  :nodefaultconst:

   usage: foo [-h] [--foo FOO] [--bar BAR] [--bla BLA]

optional arguments
   --foo

   foo help

bar options
   --foo

   foo help

   --bar

   bar help

bla options
   --foo

   foo help

   --bar

   bar help

   --bla

   bla help

Thank you for your package, comrades! It is extremely useful, but cannot you support argument choices display?

For example, when I add an argument with choices in such way

parser.add_argument('move', choices=['rock', 'paper', 'scissors'])

The choices are not displayed in argument description. They are seen only in usage string at the top of the page, that is usually too large to be read by user.

Cannot you add a display of the choices of arguments to the argument description?

It seems sphinx-argparse does not support expanding the %(default) contained in help string of the add_argument().
sphinx-argparse will literaly print "%(default)" instead of replacing it with the default argument of the add_argument().

Please, see https://docs.python.org/3/library/argparse.html#help

Thanks!

Loving the plugin, thank for it

It'd be nice to know what changes between versions (re: cihai/unihan-etl#17 and emre/kaptan#52)

Setup:
OS: Ubuntu 14.04
Sphinx: 1.3.1
Sphinxarg: 0.1.15
Python: 2.7.6

Tried install both using sudo pip install sphinxarg and sudo python setup.py installfrom source, but with same results.

sphinxarg.ext is added to conf.py as follows:

extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinxarg.ext"]

When I add the module, I get the following error:

$ make latexpdf
sphinx-build -b latex -d build/doctrees   source build/latex
Running Sphinx v1.3.1
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [latex]: all documents
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index                                                                   
Exception occurred:
  File "build/bdist.linux-x86_64/egg/sphinxarg/ext.py", line 324, in run
    mod = __import__(module_name, globals(), locals(), [attr_name])
TypeError: Item in ``from list'' not a string
The full traceback has been saved in /tmp/sphinx-err-RPSW25.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [latexpdf] Error 1

Same output for various other targets.

Any suggestions as how to get your extension working?

getting 404 not found

It is helpful to track the minimum usable version of Sphinx, especially as this also dictates the minimum version of docutils is available indirectly due to the Sphinx version. This extension uses Sphinx and docutils .

A bit of digging shows that this extension requires at least Sphinx 1.0+ , and docutils 0.5, but it might actually be higher.

sphinx.util.nodes.nested_parse_with_titles was added in sphinx-doc/sphinx@c5d67b032 (version 1.0b1)

sphinx.util.compat.Directive here was added in sphinx-doc/sphinx@f2f62501e (version 0.6.2)

And Sphinx 1.0b1 dropped support for docutils 0.4 in sphinx-doc/sphinx@f2f62501e

fwiw, Sphinx 1.0 required on ['Pygments>=0.8', 'Jinja2>=2.2', 'docutils>=0.5']

Version: sphinx-argparse==0.1.17

When I use sphinx-argparse in multiple places within my documentation, default values for string parameters seem to grow additional levels of quoting.

For example, several subcommands have a deployment-template parameter. In each place it shows as having a different number of quotes:

--deployment-template="""{tag_namespace}-{tag_version}"""

then

--deployment-template=""""{tag_namespace}-{tag_version}""""

I believe this is because sphinx-argparse mutates my (singleton) parser object, at https://github.com/ribozz/sphinx-argparse/blob/master/sphinxarg/parser.py#L114

For http://api.coala.io/en/latest/Developers/coala_settings.html we defined argument groups and I think it'd be great to have them in the generated document

It seems that most Sphinx roles, when used in the description of an argparse subcommand, cause sphinx-argparse to crash. The ones listed under "Other semantic markup" on the Roles Sphinx documentation page seems to work correctly, though.

Here is a minimal Sphinx project to reproduce this problem:

conf.py

extensions = ['sphinxarg.ext']

contents.rst

.. argparse::
   :module: sphinxtest
   :func: get_parser

sphinxtest.py

import argparse

def get_parser():
    parser = argparse.ArgumentParser()
    subparsers = parser.add_subparsers()
    subparsers.add_parser('subcmd', description=':file:`role` makes sphinx-argparse fail')
    return parser

Build command (full virtualenv paths omitted for brevity)

$ rm html -rf ; PYTHONPATH=. sphinx-build -v . html     
Running Sphinx v1.7.2
making output directory...
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] contents

Traceback (most recent call last):
  File "docutils/statemachine.py", line 307, in next_line
    self.line = self.input_lines[self.line_offset]
  File "docutils/statemachine.py", line 1152, in __getitem__
    return self.data[i]
IndexError: list index out of range

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "docutils/statemachine.py", line 230, in run
    self.next_line()
  File "docutils/statemachine.py", line 310, in next_line
    raise EOFError
EOFError

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "sphinx/cmdline.py", line 304, in main
    app.build(args.force_all, filenames)
  File "sphinx/application.py", line 331, in build
    self.builder.build_update()
  File "sphinx/builders/__init__.py", line 338, in build_update
    'out of date' % len(to_build))
  File "sphinx/builders/__init__.py", line 351, in build
    updated_docnames = set(self.env.update(self.config, self.srcdir, self.doctreedir))
  File "sphinx/environment/__init__.py", line 565, in update
    self._read_serial(docnames, self.app)
  File "sphinx/environment/__init__.py", line 584, in _read_serial
    self.read_doc(docname, app)
  File "sphinx/environment/__init__.py", line 659, in read_doc
    doctree = read_doc(self.app, self, self.doc2path(docname))
  File "sphinx/io.py", line 294, in read_doc
    pub.publish()
  File "docutils/core.py", line 217, in publish
    self.settings)
  File "docutils/readers/__init__.py", line 72, in read
    self.parse()
  File "docutils/readers/__init__.py", line 78, in parse
    self.parser.parse(self.input, document)
  File "sphinx/parsers.py", line 85, in parse
    self.statemachine.run(inputstring, document, inliner=self.inliner)
  File "docutils/parsers/rst/states.py", line 171, in run
    input_source=document['source'])
  File "docutils/statemachine.py", line 239, in run
    context, state, transitions)
  File "docutils/statemachine.py", line 460, in check_line
    return method(match, context, next_state)
  File "docutils/parsers/rst/states.py", line 2326, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "docutils/parsers/rst/states.py", line 2338, in explicit_construct
    return method(self, expmatch)
  File "docutils/parsers/rst/states.py", line 2081, in directive
    directive_class, match, type_name, option_presets)
  File "docutils/parsers/rst/states.py", line 2130, in run_directive
    result = directive_instance.run()
  File "sphinxarg/ext.py", line 486, in run
    settings=self.state.document.settings))
  File "sphinxarg/ext.py", line 192, in print_subcommands
    for element in renderList(desc, markDownHelp):
  File "sphinxarg/ext.py", line 66, in renderList
    Parser().parse('\n\n'.join(l) + '\n', document)
  File "docutils/parsers/rst/__init__.py", line 191, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "docutils/parsers/rst/states.py", line 171, in run
    input_source=document['source'])
  File "docutils/statemachine.py", line 245, in run
    result = state.eof(context)
  File "docutils/parsers/rst/states.py", line 2696, in eof
    self.blank(None, context, None)
  File "docutils/parsers/rst/states.py", line 2688, in blank
    context, self.state_machine.abs_line_number() - 1)
  File "docutils/parsers/rst/states.py", line 418, in paragraph
    textnodes, messages = self.inline_text(text, lineno)
  File "docutils/parsers/rst/states.py", line 427, in inline_text
    return self.inliner.parse(text, lineno, self.memo, self.parent)
  File "docutils/parsers/rst/states.py", line 645, in parse
    lineno)
  File "docutils/parsers/rst/states.py", line 787, in interpreted_or_phrase_ref
    lineno)
  File "docutils/parsers/rst/states.py", line 871, in interpreted
    nodes, messages2 = role_fn(role, rawsource, text, lineno, self)
  File "sphinx/roles.py", line 292, in emph_literal_role
    env = inliner.document.settings.env
AttributeError: 'Values' object has no attribute 'env'

Exception occurred:
  File "sphinx/roles.py", line 292, in emph_literal_role
    env = inliner.document.settings.env
AttributeError: 'Values' object has no attribute 'env'
The full traceback has been saved in /tmp/sphinx-err-kdcf92c8.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

I just updated sphinx-argparse and see that long argument help strings (which I typically triple-quote) are being rendered as "definition", i.e., bold first line followed by indented subsequent lines.
Argparse, of course, handles these by changing interior sequences of white space to a single blank.

I think this extension should handle long strings the same way argparse does, or at least do so optionally.

Thanks,
Rich

The manpage generated with using this extension is missing the first - in the list of options because in the generated file there is no space between the .B prefix and the line content:

.B\-c, \-\-config

This is rendered as:
c, --config
missing the first dash.

From pip freeze:

Sphinx==1.6.4
sphinx-argparse==0.2.1

Hi,

I was trying to implement an option to use nodes.rubric instead of nodes.title, but I didn't quite achieve it: j3mdamas@2b884ec

The objective was to suppress the "Positional Arguments" and "Named Arguments" from the sidebar, but maybe I am approaching this incorrectly. I was able to change them into a rubric entry, but they still appear in the sidebar. I would assume it has to do with the nodes.section being used, but this was my first time looking into docutils. Any clue? I think suppressing these from the sidebar can be useful.

João