sphinx-contrib / autoprogram Goto Github PK

When building with Sphinx 2.2.0, I get the following warning:

the sphinxcontrib.autoprogram extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit

Here's what a similar project did to fix this warning: agronholm/sphinx-autodoc-typehints@c4657bc

This module imports sphinx.util.compat which has been removed from Sphinx 1.7.

Blocking Gallopsled/pwntools#1113

As highlighted in #42, the expectations around what versions of Python this project supports are unclear. These should be documented, and every supported version should be tested in CI.

Please add a new option :label:, that adds a labels to all the created reST output:

 if is_program:
   yield '.. program:: ' + title
   yield ''

+ if 'label' in self.options:
+   yield ''
+   yield '.. _%s:' % (self.options.get('label') + title).replace(" ", "-")

 yield title
 yield ('!' if is_subgroup else '?') * len(title)
 yield ''

When packaging update of this package for openSUSE/Factory I get this test to fail:

[    4s] ======================================================================
[    4s] ERROR: test_make_rst (sphinxcontrib.autoprogram.AutoprogramDirectiveTestCase)
[    4s] ----------------------------------------------------------------------
[    4s] Traceback (most recent call last):
[    4s]   File "/usr/lib/python3.8/site-packages/sphinxcontrib/autoprogram.py", line 532, in setUp
[    4s]     self.directive = AutoprogramDirective(
[    4s]   File "/usr/lib/python3.8/site-packages/docutils/parsers/rst/__init__.py", line 331, in __init__
[    4s]     self.reporter = state_machine.reporter
[    4s] AttributeError: 'NoneType' object has no attribute 'reporter'
[    4s]

Using docutils 0.19, all other details could be found in complete build log.

Recently, the following line was added to autoprogram.py:

from __future__ import annotations

However, the annotations feature was only added in Python 3.7 per PEP 563. This breaks autoprogram on Python 3.6, which still has upstream support until the end of the year.

We encountered this problem on our CI builds for the gcovr project, which we run on 3.6 to ensure compatibility. I note that autoprogram uses 3.7 as the oldest version.

What is the intention here?

• Does autoprogram intend to support all Python versions with upstream support? If so, how can the annotations feature be made unnecessary? The annotations feature is not necessary for type annotations, but merely changes the evaluation order in order to directly support forward references.
• Or will autoprogram as a developer-focused tool only target more recent Python versions, and explicitly drop support for 3.6? If so, please mention this in the changelog.

In any case, it may be time to update the classifiers in setup.py – they claim support for Python 3.3 and Stackless Python, both of which seem like untested claims :)

Is it possible to output multiple manpages/html pages eg for commands with multiple subcommands and a lot of options? I'd like to have the main command in a page and each subcommand in a separate page.

I try as follows but don't get the expected results.

Main command rst file - I try to remove all subcommands in the output my setting maxdepth: 0 but it does not work. Still all subcommands are included in the disco section:

.. autoprogram:: discodos.cmd.cli:ArgParse.parser
    :prog: disco
    :maxdepth: 0
    :groups:

one of the subcommand rst files - works as expected, only the disco searchcommand is shown:

.. autoprogram:: discodos.cmd.cli:ArgParse.parser
    :prog: disco
    :start_command: search
    :maxdepth: 1
    :groups

I have some index rst files too and in html output what I am trying to achieve looks quite good already, except the main command issue. These are the index files:

DiscoDOS manual
***************

.. toctree::
    :maxdepth: 2

    index_commands_reference

Commands reference
******************

.. toctree::
    :maxdepth: 1

    disco
    disco_search
    disco_mix
    disco_suggest
    disco_import
    disco_setup

In manpage output I still get one big manpage, containing all subcommands. How can I control that pages should be separated?

Hi I just realised that #21 or at least something similiar appears to be still an issue in generated manpages. Not sure if it is related at all, just sounds familiar....didn't dig into any code.

eg

    search_subparser.add_argument(
        dest='release_search', metavar='search_terms',
        help="""
        The collection is searched for these terms. When offline, it
        searches through all releases' artists/titles only (eg tracknames
        not considered). When online, the Discogs API search
        ...
        """

produces in the manpage:

 positional arguments
       search_terms
              The collection is searched for these terms. When offline, it
                      searches through all releasesa artists/titles only (eg tracknames
                      not considered). When online, the Discogs API search
                      ...

.ft P
.fi
.UNINDENT
.UNINDENT
.SS positional arguments
.INDENT 0.0
.TP
.B search_terms
The collection is searched for these terms. When offline, it
        searches through all releases’ artists/titles only (eg tracknames
        not considered). When online, the Discogs API search
        ...

Usually I describe in short what a subcommand does by putting a text into a subparsers help argument. Argparser renders it like this:

$ disco -h
usage: disco [-h] [-v] [-o] {search,mix,suggest,import,setup} ...

positional arguments:
  {search,mix,suggest,import,setup}
    search              searches for releases and tracks in the Discogs
                        collection. Several actions can be executed on the
                        found items, eg. adding to a mix, updating track info
                        from Discogs or fetching additional information from
                        MusicBrainz/AcousticBrainz. View this subcommand's
                        help: disco search -h.
    mix                 manages your mixes. View this subcommand's help:
                        "disco mix -h."       
...          

This help is not shown anywhere in autoprogram generated manpages or html pages. How could I enable it so it is included in the main command section similar to how argparser shows it in main command --help?

Since I recently have no much chance to use Python at all, it's getting less motivating me to maintain this project. If someone who wish maintain this project from now on, I would like to give them all necessary accesses (this repository, PyPI, & RTD.org). No special prerequisites, but it would be great if them have experience of developing any Sphinx extensions or sending patches to this project.

Is there a way not to add a program to TOC?
https://rna-tools.readthedocs.io/en/latest/

How does autoprogram compare against argdoc?

https://github.com/sphinx-contrib/argdoc

It looks like argdoc is not supported anymore and the recommended way to go is autoprogram?

Thanks!

There does not appear to be a way to mock modules imported by programs that autoprogram imports. It would be nice to have a mechanism to mock modules for autoprogram.

During regular development, this isn't a problem. In order to test the code, you need to have everything installed anyway. This is more of an obstacle with documentation systems that use CI resources (e.g. readthedocs.org). If your programs have imports with heavy duty dependencies (modules like gdal/osgeo which has C dependencies), those modules and libraries need to be installed, otherwise the "import" that autoprogram does results in a ModuleNotFoundError. However, in most cases, the function that produces the argument parser that autoprogram needs to deal with probably doesn't rely on those hefty imported modules, and if there was a way to mock them, then they wouldn't need to be installed and/or compiled by CI systems that just build documentation, making documentation development easier, faster, cheaper, and contributing less to the heat death of the planet.

The sphinx.ext.autodoc extension has a autodoc_mock_imports parameter that might be a model (maybe some functions could just be used, since it is always installed with Sphinx?) which allows a user to tell autodoc to mock a set of modules. This means that those modules don't need to be installed into the CI system if it is only building the docs.

Maybe we need an autoprogram_mock_imports parameter?

Hi,

When using autoprogram, I always get some options included that I'd rather remove. The most obvious one being the default --help option.

I could use argparse.SUPPRESS to remove it from the sphinx documentation, but then it will also be removed from the CLI help, and I don't want that.

Would it be possible to get a new release of sphinxcontrib-autoprogram cut and released to PyPI? The current PyPI release is nearly two years behind master.

In particular, it'd be fantastic to be able to use the fix in #11.

Thanks a ton!

Travis is shutting down its free CI for open-source projects, so we should migrate this project to Github Actions.

I have packaged sphinxcontrib-autoprogram for openSUSE, it has been accepted and is now available in Tumbleweed.

As the package maintainer, I am watching this repository and will update it on new releases. If there is something that needs backporting in between releases feel free to ping me.

(Fell free to close this issue, this is just an FYI)

Dear autoprogram team,

If I have a code like this:

if __name__ == "__main__":
    logger.setLevel("DEBUG")

    parser = argparse.ArgumentParser(
        description="""random"""
    )

then the autoprogram is unable to see the parser object for that specific file. Moving parser up before the if works, but require all the add_argument to be above the if __name__ == "__main__".

I usually declare the parser only if this is executed as a script or with the -m option of python, and tend to avoid global objects otherwise.

Is there a way to make it work like this?

Thank you,

Hi,

I am currently packaging autoprogram for OpenSUSE and have run into the issue that I don't know under which BSD license this package is licensed (there's multiple different BSD licenses).

Could you please specify the license in the setup.py (and preferably create a COPYING.txt, too)? (Or tell me which BSD license it is and I'll create a pull request).

Thanks!
Dan

The documentation is broken with latest Sphinx release, 6.1.3:

sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v6.1.3
WARNING: html_static_path entry '_static' does not exist
loading intersphinx inventory from http://docs.python.org/objects.inv...
loading intersphinx inventory from http://sphinx-doc.org/objects.inv...
intersphinx inventory has moved: http://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
intersphinx inventory has moved: http://sphinx-doc.org/objects.inv -> https://www.sphinx-doc.org/en/master/
WARNING: failed to reach any of the inventories with the following issues:
intersphinx inventory 'http://sphinx-doc.org/objects.inv' not readable due to ValueError: unknown or unsupported inventory version: ValueError('invalid inventory header: ')
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 2 source files that are out of date
updating environment: [new config] 2 added, 0 changed, 0 removed
reading sources... [ 50%] changelog                                                                                                                                                                                
Exception occurred:
  File "/home/danigm/Projects/suse/tmp/autoprogram/env/lib64/python3.10/site-packages/sphinx/ext/extlinks.py", line 103, in role
    title = caption % part
TypeError: not all arguments converted during string formatting
The full traceback has been saved in /tmp/sphinx-err-0wuln2p9.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!

Due to changes in python/cpython#23858 "optional arguments" has become "options" in Python 3.10 causing test case failures.

python setup.py test
running test
WARNING: Testing via this command is deprecated and will be removed in a future version. Users looking for a generic test entry point independent of test runner are encouraged to use tox.
running egg_info
writing sphinxcontrib_autoprogram.egg-info/PKG-INFO
writing dependency_links to sphinxcontrib_autoprogram.egg-info/dependency_links.txt
writing namespace_packages to sphinxcontrib_autoprogram.egg-info/namespace_packages.txt
writing requirements to sphinxcontrib_autoprogram.egg-info/requires.txt
writing top-level names to sphinxcontrib_autoprogram.egg-info/top_level.txt
reading manifest file 'sphinxcontrib_autoprogram.egg-info/SOURCES.txt'
reading manifest template 'MANIFEST.in'
warning: no files found matching 'README'
warning: no files found matching 'CHANGES.*'
writing manifest file 'sphinxcontrib_autoprogram.egg-info/SOURCES.txt'
running build_ext
test_argument_groups (sphinxcontrib.autoprogram.ScannerTestCase) ... FAIL
test_choices (sphinxcontrib.autoprogram.ScannerTestCase) ... ok
test_parse_epilog (sphinxcontrib.autoprogram.ScannerTestCase) ... ok
test_simple_parser (sphinxcontrib.autoprogram.ScannerTestCase) ... ok
test_subcommands (sphinxcontrib.autoprogram.ScannerTestCase) ... ok
test_make_rst (sphinxcontrib.autoprogram.AutoprogramDirectiveTestCase)
Alt least it shouldn't raise errors during making RST string. ... ok
test_import_object (sphinxcontrib.autoprogram.UtilTestCase) ... ok

======================================================================
FAIL: test_argument_groups (sphinxcontrib.autoprogram.ScannerTestCase)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/root/checked_repos/autoprogram/sphinxcontrib/autoprogram.py", line 427, in test_argument_groups
    self.assertEqual('optional arguments', group.title)
AssertionError: 'optional arguments' != 'options'
- optional arguments
+ options


----------------------------------------------------------------------
Ran 7 tests in 0.012s

FAILED (failures=1)
Test failed: <unittest.runner.TextTestResult run=7 errors=0 failures=1>
error: Test failed: <unittest.runner.TextTestResult run=7 errors=0 failures=1>

I've been trying to cross-reference arguments in my autoprogram output and can't find any viable way to do it.

According to python3 -m sphinx.ext.intersphinx, these are the cross-reference targets that are being generated...

std:cmdoption
        quicktile.--bindkeys                     cli.html#cmdoption-quicktile-b
        quicktile.--daemonize                    cli.html#cmdoption-quicktile-d
        quicktile.--debug                        cli.html#cmdoption-quicktile-debug
        quicktile.--help                         cli.html#cmdoption-quicktile-h
        quicktile.--no-workarea                  cli.html#cmdoption-quicktile-no-workarea
        quicktile.--show-actions                 cli.html#cmdoption-quicktile-show-actions
        quicktile.--show-bindings                cli.html#cmdoption-quicktile-show-bindings
        quicktile.--version                      cli.html#cmdoption-quicktile-v
        quicktile.-V                             cli.html#cmdoption-quicktile-v
        quicktile.-b                             cli.html#cmdoption-quicktile-b
        quicktile.-d                             cli.html#cmdoption-quicktile-d
        quicktile.-h                             cli.html#cmdoption-quicktile-h
        quicktile.command                        cli.html#cmdoption-quicktile-arg-command

...and, according to the Sphinx docs, cmdoption is a deprecated alias for option, but I get WARNING: unknown option when I try to use :option: or :any: to cross-reference either quicktile.--show-bindings or --show-bindings.

I've taken to the hacky and not-quite-right-looking solution of using this syntax for my option cross-references:

`-\\-show-bindings <cli.html#cmdoption-quicktile-show-bindings>`_

EDIT: The -\\- hack is broken in the manpage output. I had to resort to just disabling SmartyPants.
EDIT: Correction: I have to special-case manpage output because html_use_smartypants = False is getting ignored.

Usage fails on python 3.6.12

    from __future__ import annotations
    ^
SyntaxError: future feature annotations is not defined

https://stackoverflow.com/questions/52889746/cant-import-annotations-from-future

This package is declared python 3 only, thus six usage should not be necessary.

Is it possible to include the doc dir to the sdist release? Without doc you can't complete all unit tests nor can you install docs.

I'm packaging your module as an rpm package so I'm using the typical PEP517 based build, install and test cycle used on building packages from non-root account.

• python3 -sBm build -w --no-isolation
• because I'm calling build with --no-isolation I'm using during all processes only locally installed modules
• install .whl file in </install/prefix> using 'installer` module
• run pytest with $PYTHONPATH pointing to sitearch and sitelib inside </install/prefix>
• build is performed in env which is cut off from access to the public network (pytest is executed with -m "not network")

Here is pytest output:

+ PYTHONPATH=/home/tkloczko/rpmbuild/BUILDROOT/python-sphinxcontrib-autoprogram-0.1.8-3.fc35.x86_64/usr/lib64/python3.8/site-packages:/home/tkloczko/rpmbuild/BUILDROOT/python-sphinxcontrib-autoprogram-0.1.8-3.fc35.x86_64/usr/lib/python3.8/site-packages
+ /usr/bin/pytest -ra -m 'not network' sphinxcontrib/autoprogram.py
==================================================================================== test session starts ====================================================================================
platform linux -- Python 3.8.17, pytest-7.4.0, pluggy-1.2.0
rootdir: /home/tkloczko/rpmbuild/BUILD/autoprogram-0.1.8
collected 8 items

sphinxcontrib/autoprogram.py EEEEEEEE                                                                                                                                                 [100%]

========================================================================================== ERRORS ===========================================================================================
__________________________________________________________________ ERROR at setup of ScannerTestCase.test_argument_groups ___________________________________________________________________

app = <module 'autoprogram' from '/home/tkloczko/rpmbuild/BUILD/autoprogram-0.1.8/sphinxcontrib/autoprogram.py'>

    def setup(app) -> Dict[str, bool]:
>       app.add_directive("autoprogram", AutoprogramDirective)
E       AttributeError: module 'autoprogram' has no attribute 'add_directive'

sphinxcontrib/autoprogram.py:338: AttributeError
______________________________________________________________________ ERROR at setup of ScannerTestCase.test_choices _______________________________________________________________________

app = <module 'autoprogram' from '/home/tkloczko/rpmbuild/BUILD/autoprogram-0.1.8/sphinxcontrib/autoprogram.py'>

    def setup(app) -> Dict[str, bool]:
>       app.add_directive("autoprogram", AutoprogramDirective)
E       AttributeError: module 'autoprogram' has no attribute 'add_directive'

sphinxcontrib/autoprogram.py:338: AttributeError
____________________________________________________________________ ERROR at setup of ScannerTestCase.test_parse_epilog ____________________________________________________________________

app = <module 'autoprogram' from '/home/tkloczko/rpmbuild/BUILD/autoprogram-0.1.8/sphinxcontrib/autoprogram.py'>

    def setup(app) -> Dict[str, bool]:
>       app.add_directive("autoprogram", AutoprogramDirective)
E       AttributeError: module 'autoprogram' has no attribute 'add_directive'

sphinxcontrib/autoprogram.py:338: AttributeError
___________________________________________________________________ ERROR at setup of ScannerTestCase.test_simple_parser ____________________________________________________________________

app = <module 'autoprogram' from '/home/tkloczko/rpmbuild/BUILD/autoprogram-0.1.8/sphinxcontrib/autoprogram.py'>

    def setup(app) -> Dict[str, bool]:
>       app.add_directive("autoprogram", AutoprogramDirective)
E       AttributeError: module 'autoprogram' has no attribute 'add_directive'

sphinxcontrib/autoprogram.py:338: AttributeError
____________________________________________________________________ ERROR at setup of ScannerTestCase.test_subcommands _____________________________________________________________________

app = <module 'autoprogram' from '/home/tkloczko/rpmbuild/BUILD/autoprogram-0.1.8/sphinxcontrib/autoprogram.py'>

    def setup(app) -> Dict[str, bool]:
>       app.add_directive("autoprogram", AutoprogramDirective)
E       AttributeError: module 'autoprogram' has no attribute 'add_directive'

sphinxcontrib/autoprogram.py:338: AttributeError
_______________________________________________________________ ERROR at setup of AutoprogramDirectiveTestCase.test_make_rst ________________________________________________________________

app = <module 'autoprogram' from '/home/tkloczko/rpmbuild/BUILD/autoprogram-0.1.8/sphinxcontrib/autoprogram.py'>

    def setup(app) -> Dict[str, bool]:
>       app.add_directive("autoprogram", AutoprogramDirective)
E       AttributeError: module 'autoprogram' has no attribute 'add_directive'

sphinxcontrib/autoprogram.py:338: AttributeError
_____________________________________________________________________ ERROR at setup of UtilTestCase.test_import_object _____________________________________________________________________

app = <module 'autoprogram' from '/home/tkloczko/rpmbuild/BUILD/autoprogram-0.1.8/sphinxcontrib/autoprogram.py'>

    def setup(app) -> Dict[str, bool]:
>       app.add_directive("autoprogram", AutoprogramDirective)
E       AttributeError: module 'autoprogram' has no attribute 'add_directive'

sphinxcontrib/autoprogram.py:338: AttributeError
______________________________________________________________________ ERROR at setup of test_case.test_import_object _______________________________________________________________________

app = <module 'autoprogram' from '/home/tkloczko/rpmbuild/BUILD/autoprogram-0.1.8/sphinxcontrib/autoprogram.py'>

    def setup(app) -> Dict[str, bool]:
>       app.add_directive("autoprogram", AutoprogramDirective)
E       AttributeError: module 'autoprogram' has no attribute 'add_directive'

sphinxcontrib/autoprogram.py:338: AttributeError
================================================================================== short test summary info ==================================================================================
ERROR sphinxcontrib/autoprogram.py::ScannerTestCase::test_argument_groups - AttributeError: module 'autoprogram' has no attribute 'add_directive'
ERROR sphinxcontrib/autoprogram.py::ScannerTestCase::test_choices - AttributeError: module 'autoprogram' has no attribute 'add_directive'
ERROR sphinxcontrib/autoprogram.py::ScannerTestCase::test_parse_epilog - AttributeError: module 'autoprogram' has no attribute 'add_directive'
ERROR sphinxcontrib/autoprogram.py::ScannerTestCase::test_simple_parser - AttributeError: module 'autoprogram' has no attribute 'add_directive'
ERROR sphinxcontrib/autoprogram.py::ScannerTestCase::test_subcommands - AttributeError: module 'autoprogram' has no attribute 'add_directive'
ERROR sphinxcontrib/autoprogram.py::AutoprogramDirectiveTestCase::test_make_rst - AttributeError: module 'autoprogram' has no attribute 'add_directive'
ERROR sphinxcontrib/autoprogram.py::UtilTestCase::test_import_object - AttributeError: module 'autoprogram' has no attribute 'add_directive'
ERROR sphinxcontrib/autoprogram.py::test_case::test_import_object - AttributeError: module 'autoprogram' has no attribute 'add_directive'
===================================================================================== 8 errors in 0.31s =====================================================================================

Here is list of installed modules in build env

Package                       Version
----------------------------- -------
alabaster                     0.7.13
Babel                         2.12.1
build                         0.10.0
charset-normalizer            3.2.0
distro                        1.8.0
docutils                      0.19
exceptiongroup                1.1.1
gpg                           1.20.0
idna                          3.4
imagesize                     1.4.1
importlib-metadata            6.8.0
iniconfig                     2.0.0
installer                     0.7.0
Jinja2                        3.1.2
libcomps                      0.1.19
MarkupSafe                    2.1.2
packaging                     23.1
pluggy                        1.2.0
Pygments                      2.16.0
pyproject_hooks               1.0.0
pytest                        7.4.0
python-dateutil               2.8.2
pytz                          2023.2
requests                      2.31.0
setuptools                    68.0.0
six                           1.16.0
snowballstemmer               2.2.0
Sphinx                        6.2.1
sphinxcontrib-applehelp       1.0.4
sphinxcontrib-devhelp         1.0.2
sphinxcontrib-htmlhelp        2.0.0
sphinxcontrib-jsmath          1.0.1
sphinxcontrib-qthelp          1.0.3
sphinxcontrib-serializinghtml 1.1.5
tomli                         2.0.1
urllib3                       1.26.15
wheel                         0.40.0
zipp                          3.16.2

I'm looking to use sphinxcontrib-autoprogram to embed the argparse help into a manpage of sorts.

But .. autoprogram:: adds a section head containing the :prog: name like so:

(It's the "aiosmtpd" line right under "SYNOPSIS". rst source code is as follows:)

SYNOPSIS
========

.. autoprogram:: aiosmtpd.main:_parser()
   :prog: aiosmtpd

Please add an option/directive such as :notitle: to suppress this.

Auto-formatting is helpful because:

• it enforces a uniform style, making the code easier to read; and
• it removes any possibility of disagreement about formatting, contributing to a healthier project culture.

https://github.com/psf/black#how-black-wraps-lines

Currently, tox.ini specifies Sphinx versions 1.2.0-1.8.0, but Sphinx is now at 3.4.3. We should test against newer versions!

We should add Python 3.12 to setup.py, tox.ini, and Github actions.

Hey, thanks for a great package!! I don't think the below is a huge issue, but I just spent a few hours debugging it, so I figured I would pass it along.

In my understanding, there are two, roughly equivalent ways one might structure their argparse usage. I won't opine on the relative benefits, only that I've seen both in the wild.

method 1:

def parse_arguments():
    parser = argparse.ArgumentParser()
    # blah blah blah
    return parser

def main():
    parser = parse_arguments()
    args = parser.parse_args()

method 2:

def parse_arguments():
    parser = argparse.ArgumentParser()
    # blah blah blah
    return parser.parse_args()

def main():
    args = parse_arguments()

Method 1 works with autoprogram, and is what is outlined in the docs. However, method 2 doesn't work, and actually raises a pretty unhelpful error message. I don't think there's any reason to support method 2, and I could imagine that would be a headache to implement anyway. But, I think it might be possible to detect that a user has done this and raise a helpful error, or even simpler, add a clarifying sentence or two in the docs. (Or even simpler, just leave this issue open for others to find!)

With blessing, I'd be happy to take a stab at editing the docs accordingly. Thanks!

After #28 is sorted out, I'd like to make CI a required "status check" for merging and add this to Github's "branch protections".

Mypy helps us avoid simple errors. This should be integrated into CI.

http://mypy-lang.org/

Many packages have switched to leverage PEP 517 style of building the package, dropping setuptools in the process.

At the same time, it may be worth considering changing setup.py into a more declarative pyproject.toml (or setup.cfg).

I'm using autoprogram to document a Python script that uses argparse with a custom Formatter class that inherits from argparse.ArgumentDefaultsHelpFormatter and argparse.RawDescriptionHelpFormatter.
The RST string returned by the render_rst() function defined in autoprogram.py is not aware of the formatter and therefore the default value (default = xxx) is not added to the help string.
I noticed that the parser instance inside the make_rst() method of the AutoprogramDirective class defined in autoprogram.py has a _get_formatter() method that returns the formatter and that the formatter object has a _format_action() method that correctly formats the action. I do not know if this can help in adding this feature to autoprogram.py but your opinion would be very appreciated.
Roberto

Python 3.12 has dropped the imp module which is used at

Exception occurred:
  File "/usr/lib/python3.12/site-packages/sphinxcontrib/autoprogram.py", line 148, in import_object
    import imp
ModuleNotFoundError: No module named 'imp'
The full traceback has been saved in /tmp/sphinx-err-qnsv37t_.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 get this when running against one of my parsers.

reading sources... [ 10%] cli
Exception occurred:
  File "/anaconda2/envs/ionic-fs-watcher/lib/python3.6/site-packages/sphinxcontrib/autoprogram.py", line 103, in format_option
    value = '{{{0}}}'.format(','.join(arg.choices))
TypeError: sequence item 0: expected str instance, int found
The full traceback has been saved in /var/folders/m2/kzfqsnk915x24ddpjt6fggmmh_bxtz/T/sphinx-err-jqa3ku_t.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!

Here is the bottom part of that /var/folders/m2/kzfqsnk915x24ddpjt6fggmmh_bxtz/T/sphinx-err-jqa3ku_t.log file

  File "/anaconda2/envs/ionic-fs-watcher/lib/python3.6/site-packages/docutils/parsers/rst/states.py", line 2081, in directive
    directive_class, match, type_name, option_presets)
  File "/anaconda2/envs/ionic-fs-watcher/lib/python3.6/site-packages/docutils/parsers/rst/states.py", line 2130, in run_directive
    result = directive_instance.run()
  File "/anaconda2/envs/ionic-fs-watcher/lib/python3.6/site-packages/sphinxcontrib/autoprogram.py", line 236, in run
    for line in self.make_rst():
  File "/anaconda2/envs/ionic-fs-watcher/lib/python3.6/site-packages/sphinxcontrib/autoprogram.py", line 201, in make_rst
    parser, maxdepth=maxdepth, groups=groups
  File "/anaconda2/envs/ionic-fs-watcher/lib/python3.6/site-packages/sphinxcontrib/autoprogram.py", line 73, in scan_programs
    sub, command + [cmd], maxdepth, depth + 1
  File "/anaconda2/envs/ionic-fs-watcher/lib/python3.6/site-packages/sphinxcontrib/autoprogram.py", line 73, in scan_programs
    sub, command + [cmd], maxdepth, depth + 1
  File "/anaconda2/envs/ionic-fs-watcher/lib/python3.6/site-packages/sphinxcontrib/autoprogram.py", line 55, in scan_programs
    options = list(scan_options(parser._actions))
  File "/anaconda2/envs/ionic-fs-watcher/lib/python3.6/site-packages/sphinxcontrib/autoprogram.py", line 86, in scan_options
    yield format_option(arg)
  File "/anaconda2/envs/ionic-fs-watcher/lib/python3.6/site-packages/sphinxcontrib/autoprogram.py", line 103, in format_option
    value = '{{{0}}}'.format(','.join(arg.choices))
TypeError: sequence item 0: expected str instance, int found

The suspect code is here, which fails with integer values

    if arg.choices is not None:
        value = '{{{0}}}'.format(','.join(arg.choices))

Changing to something this should fix it

    if arg.choices is not None:
        value = '{{{0}}}'.format(','.join(str(c) for c in arg.choices))

Sub-commands of argument parser always get sorted in the Sphinx documentation page generated with 'autoprogram'. There's no good way to turn alphabet sorting off (except maybe tricking with OrderedDict class, which breaks other functionality).

In my use case sorting of sub-commands produces misleading documentation, and I want to avoid sorting.

In autoprogram.py:

choices = sorted(choices, key=lambda pair: pair[0])

I suggest adding an option for 'autoprogram', for example: ":no_sorting:".