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>
Tweak logic that rejects a :numref: if numfig is not on to bypass this
check if the reference is a section. Section numbers are applied
independent of numfig, so the check is not needed, and makes it
needlessly difficult to use :numref: if the user only cares about using
it on sections.
