sphinx-apidoc doesn't accept 'exclude_patterns'

[stephenfin]

Subject: sphinx-apidoc in Sphinx 1.7+ doesn't accept the exclude_patterns parameter

Problem

If I want to exclude some modules from sphinx-apidoc doc generation, I can just list them as additional arguments. For example:

$ sphinx-apidoc . -H 'Modules' -o doc/source/contributor/api setup.py \
  openstackclient/volume/v3 openstackclient/tests/ openstackclient/tests/*

This works with Sphinx 1.6.x but fails with Sphinx 1.7.x. I think I broke this in the move to argparse but, try as I may, I can't figure out how to fix it 😞

Procedure to reproduce the problem

$ git clone https://github.com/openstack/python-openstackclient
$ cd python-openstackclient
$ tox -e docs  # to install all dependencies

Now, build docs with the current version of Sphinx used (1.6.5):

$ sphinx-apidoc . -H 'Modules' -o doc/source/contributor/api setup.py openstackclient/volume/v3 openstackclient/tests/ openstackclient/tests/*

Then attempt to do the same with the latest Sphinx (1.7.2):

$ pip install 'sphinx>=1.7'
$ sphinx-apidoc . -H 'Modules' -o doc/source/contributor/api setup.py openstackclient/volume/v3 openstackclient/tests/ openstackclient/tests/*

Error logs / results

$ sphinx-apidoc . -H 'Modules' -o doc/source/contributor/api setup.py openstackclient/volume/v3 openstackclient/tests/ openstackclient/tests/*                
usage: sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN, ...]
sphinx-apidoc: error: unrecognized arguments: setup.py openstackclient/volume/v3 openstackclient/tests/ openstackclient/tests/*

Expected results

$ sphinx-apidoc . -H 'Modules' -o doc/source/contributor/api setup.py openstackclient/volume/v3 openstackclient/tests/ openstackclient/tests/*                                                                     
Creating file doc/source/contributor/api/openstackclient.rst.
Creating file doc/source/contributor/api/openstackclient.api.rst.
Creating file doc/source/contributor/api/openstackclient.common.rst.
Creating file doc/source/contributor/api/openstackclient.compute.rst.
Creating file doc/source/contributor/api/openstackclient.compute.v2.rst.
Creating file doc/source/contributor/api/openstackclient.identity.rst.
Creating file doc/source/contributor/api/openstackclient.identity.v2_0.rst.
Creating file doc/source/contributor/api/openstackclient.identity.v3.rst.
Creating file doc/source/contributor/api/openstackclient.image.rst.
Creating file doc/source/contributor/api/openstackclient.image.v1.rst.
Creating file doc/source/contributor/api/openstackclient.image.v2.rst.
Creating file doc/source/contributor/api/openstackclient.network.rst.
Creating file doc/source/contributor/api/openstackclient.network.v2.rst.
Creating file doc/source/contributor/api/openstackclient.object.rst.
Creating file doc/source/contributor/api/openstackclient.object.v1.rst.
Creating file doc/source/contributor/api/openstackclient.volume.rst.
Creating file doc/source/contributor/api/openstackclient.volume.v1.rst.
Creating file doc/source/contributor/api/openstackclient.volume.v2.rst.
Creating file doc/source/contributor/api/modules.rst.

Reproducible project / your project

• https://github.com/openstack/python-openstackclient (though this happens with every project)

Environment info

• OS: Linux
• Python version: 2.7
• Sphinx version: 1.7.2

[tk0miya]

I guess this comes from the order of command line arguments.

usage: sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN, ...]

As usage says, argparse expects positional arguments are placed after all of options.
How about this?

$ sphinx-apidoc -H 'Modules' -o doc/source/contributor/api . setup.py openstackclient/volume/v3 openstackclient/tests/ openstackclient/tests/*

(I don't tested this on my local, sorry)

[stephenfin]

As usage says, argparse expects positional arguments are placed after all of options.

Yes, this was this issue. After talking with other folks, it seems this is a known issue with argparse (though I haven't found the upstream bug yet). I will attempt to work on this at some point but it's not a Sphinx bug. I am, however, going to keep this open in case we want to call this out in the release notes. I'll let you make that decision, @tk0miya.

[stephenfin]

After talking with other folks, it seems this is a known issue with argparse (though I haven't found the upstream bug yet).

Actually, this looks like the bug.

[tk0miya]

Hmm... I can't imagine the impact of this issue. Personally, I always uses BSD-styled options (options first, arguments last). So I think this is very minor and no-confusable change.
But, actually, this is incompatible change for Sphinx. So it would be better to mention this to users.

[tk0miya]

Fixed by #4854.