alex-rudakov / sphinx-argparse Goto Github PK
View Code? Open in Web Editor NEWSphinx extension that automatically document argparse commands and options
License: MIT License
Sphinx extension that automatically document argparse commands and options
License: MIT License
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?
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']
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.
Related to #44, the following still need to be finalized:
Additionally, it would be nice to render reStructuredText and Markdown in command descriptions and help messages:
This would require an additional directive option (:renderHelp: reStructuredText
or :renderHelp:Markdown
maybe).
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
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
getting 404 not found
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!
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)
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()
/src/doc/cli.rst:2: WARNING: duplicate label named arguments, other instance in /src/doc/cli.rst
/src/doc/cli.rst:2: WARNING: duplicate label named arguments, other instance in /src/doc/cli.rst
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'
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.
Epilog just gets ignored. Would be nice if it would be shown as it might contain examples.
Arguments (both required and optional) with empty string as default value are rendered like this:
name= | Argument with empty default |
---|
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.
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
Add passparser to the documentation somewhere please. Right now it's only referenced in the changelog.
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?
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"
.
Given that this isn't widely available currently, this would make it easier for me to package for internal use at work.
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.
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).
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
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
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
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:
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.
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
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
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
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!
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:
description
is given, the help
should probably not be displayed.@replace
directive currently replaces only the help
text; the description
is still shown.@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!
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
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
In basic usage the noepilog
option is spelled noepilogue
which is wrong in respect to the corresponding code.
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 install
from 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?
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
Mock
imports are currently not supported. It would be great if sphinx-argparse
would use the autodoc_mock_imports
list provided in conf.py
.
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
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?
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.
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)
The options table isn't very well readable :/ See http://api.coala.io/en/latest/Developers/coala_settings.html
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.
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:
SYNOPSIS
section with the synopsis of the commandDESCRIPTION
section with the description taken from the argparse parserOPTION
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
``
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.