Commit 2d99648e99 changed the apidoc
extension to ignore packages if the __init__.py file was empty. That
breaks the toctree structure if those packages do contain submodules
and subpackages. This patch adds a check to ensure that empty
__init__.py modules are only skipped if there are no other python
modules in the same directory.
Addresses bug #654
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
The signature for the 'sphinx-apidoc' call differs between the man page
and the output of 'sphinx-apidoc --help'. Resolve this by considering
the 'sphinx-apidoc --help' output the canonical reference.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Fixes: #4451
A small number of URL's redirected, or were stale but had obvious
alternatives. These have been updated. For example, a Google style
guide for Python was no longer available at googlecode.com, and
Paver docs are now at readthedocs.io.
The instructions for installing pip are no longer relevant and have
been removed. The instructions for modifying the PATH are no longer
relevant and have been removed. The final section, "Installing Sphinx
with pip", is now a subsection of the Windows install instructions.
The verb tense has been modified to match the rest of the instructions.
The command line examples have been converted to use the Pygments text
lexer instead of the batch lexer, which highlights everything after `>`
incorrectly.
Don't create the build or doctree directories. These are already handled
by 'sphinx.application.Application' and 'sphinx.builder.Builder',
respectively.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This allows us to avoid duplication of code and ensure validation
happens regardless of who's initializing the class. We introduce a new
exception - ApplicationError - to indicate these kinds of issues. This
subclasses SphinxError, meaning we don't need to modify our exception
handling code.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This allows us to do something like 'help(sphinx.errors)' in code. We
reword the exception descriptions per Python stdlib conventions.
Signed-off-by: Stephen Finucane <stephen@that.guru>
