Sphinx: Correct use of exclude_paths with sphinx-apidoc

[shimizukawa]

Maybe it's just me but apidoc seems to ignore my exclude_paths which I have set as the tests folder of my package.

sphinx-apidoc -o docs . tests

Does not work as expected. What should it look like for tests not to be scanned and documented by apidoc?

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/979
• Originally reported by: Charlie Clark
• Originally created at: 2012-07-25T22:32:29.454

[shimizukawa]

_From Jon Waltman on 2012-12-05 20:58:24+00:00_

The docs are indeed pretty vague on this argument and refer to it differently in sphinx-apidoc -h and the manual and other places.

I assumed it was a glob-style pattern but its not. Its looks like its assumed to be a directory name relative to the output directory (the -o option) or some such.

[shimizukawa]

_From Jon Waltman on 2012-12-09 06:16:52+00:00_

Having looked more into this, I think this is actually a bug in sphinx-apidoc and the exclude_paths only work if they're absolute.

I think the behavior of sphinx-apidoc should be changed so that exclude_paths are glob-style patterns based on the input directory. They can match individual files or entire directories.

This shouldn't affect backward compatibility since absolute paths would still work like before.

[shimizukawa]

_From leo-the-manic on 2013-06-26 18:09:34+00:00_

Perhaps this is less problematic in larger projects, but this is actually a pretty noticeable pain with my small web projects. I use Django and all the test packages get auto documented, adding a lot of noise. Is there any chance of this getting some attention? Would it be difficult for a newcomer to just jump in? If this is a relatively simple ticket waiting for a patch I'd be happy to give it a go.

[shimizukawa]

_From Anonymous on 2013-06-30 13:20:48+00:00_

Also create_package_file doesn't check anymore whether a sub should be excluded, so it is included in the text for the root

[shimizukawa]

_From Georg Brandl on 2014-01-19 09:10:25+00:00_

Issue #931 was marked as a duplicate of this issue.

[shimizukawa]

_From Georg Brandl on 2014-01-19 09:13:05+00:00_

Closes #979: Fix exclude handling in sphinx-apidoc.

→ <>

[shimizukawa]

_From Georg Brandl on 2014-01-19 09:25:31+00:00_

Issue #813 was marked as a duplicate of this issue.

[cesarcruz]

@shimizukawa have you tried with this sphinx-apidoc -o docs . tests/*? it seem to works.

[shimizukawa]

Thanks. (but this is not my posts. I just copied them from Bitbucket.. anyhow, thanks!)

[shimizukawa]

Memo: sphinx-apidoc -o docs . tests/* works fine because shell expands tests/* before sphinx is invoked.
So, on Windows environment, shell doesn't expand wildcard. On unix environment, sphinx-apidoc -o docs . "tests/*" doesn't work too.

930 is for this.