diff --git a/doc/invocation.rst b/doc/invocation.rst index 2c69d32f9..258c87b88 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -227,6 +227,15 @@ The :program:`sphinx-apidoc` script has several options: This sets the maximum depth of the table of contents, if one is generated. +.. option:: -l, --follow-links + + This option makes sphinx-apidoc follow symbolic links when recursing the + filesystem to discover packages and modules. You may need it if you want + to generate documentation from a source directory managed by + `collective.recipe.omelette + `_. + By default, symbolic links are skipped. + .. option:: -T, --no-toc This prevents the generation of a table-of-contents file ``modules.rst``. diff --git a/sphinx/apidoc.py b/sphinx/apidoc.py index ec1a8a33f..0f937108d 100644 --- a/sphinx/apidoc.py +++ b/sphinx/apidoc.py @@ -157,7 +157,8 @@ def recurse_tree(rootpath, excludes, opts): root_package = None toplevels = [] - for root, subs, files in os.walk(rootpath): + followlinks = getattr(opts, 'followlinks', False) + for root, subs, files in os.walk(rootpath, followlinks=followlinks): if is_excluded(root, excludes): del subs[:] continue @@ -246,6 +247,10 @@ Note: By default this script will not overwrite already created files.""") '(default: 4)', type='int', default=4) parser.add_option('-f', '--force', action='store_true', dest='force', help='Overwrite all files') + parser.add_option('-l', '--follow-links', action='store_true', + dest='followlinks', default=False, + help='Follow symbolic links. Powerful when combined ' \ + 'with collective.recipe.omelette.') parser.add_option('-n', '--dry-run', action='store_true', dest='dryrun', help='Run the script without creating files') parser.add_option('-T', '--no-toc', action='store_true', dest='notoc',