sphinx-apidoc discovers packages and modules via os.walk().
By default, os.walk() skips symbolic links. So does sphinx-apidoc.
This pull request introduces a --followlinks (alias -l) option to make sphinx-apidoc follow symbolic links.
By default, the former behaviour of sphinx-apidoc is preserved. I mean, symbolic links are skipped by default, so that the command remains backward-compatible.
Here is an use case... I am using http://pypi.python.org/pypi/collective.recipe.omelette/ to ease navigation in sourcecode. In this "omelette", I install some projects using namespace packages. Let's call them "foo.bar" and "foo.baz". So I get "omelette/foo/bar/" and "omelette/foo/baz folders". I'd like to run sphinx-apidoc on foo/ folder to generate API documentation for both foo.bar and foo.baz with one command. Since omelette uses symbolic links, I need sphinx-apidoc to care about symbolic links too. Or I only get documentation for the (empty) "foo" package.