This is placed in a directory as this document will eventually be split
up. However, this is not the day to do this.
Signed-off-by: Stephen Finucane <stephen@that.guru>
There are a number of cleanup items.
- Some paragraphs are reworded or clarified
- Semantic markup is added where possible
- Everything is wrapped to ~80 characters
A number of TODOs are inserted. These will be resolved separately.
Signed-off-by: Stephen Finucane <stephen@that.guru>
There are a number of cleanup items.
- Some paragraphs are reworded or clarified
- Semantic markup is added where possible
- Everything is wrapped to ~80 characters
Signed-off-by: Stephen Finucane <stephen@that.guru>
Resolves the following warning when building docs:
sphinx/ext/autosummary/__init__.py:94: DeprecationWarning: invalid
escape sequence \.
periods_re = re.compile('\.(?:\s+)')
Signed-off-by: Stephen Finucane <stephen@that.guru>
This makes the section more consistent with the rest of the document.
This adds a new section to the basics guide for doctest blocks, which
are a docutils thing. It also update the default highlight language,
which is now 'default'.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Finish building up this combined doc by adding the contents of the
former 'misc' document. There are no changes to the content.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Continue building up this combined doc by adding the contents of the
former 'code' document. There are no changes to the content.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Continue building up this combined doc by adding the contents of the
former 'para' document. There are no changes to the content.
Signed-off-by: Stephen Finucane <stephen@that.guru>
There's simply no need to artificially divide up the documentation on
directives into multiple, hard-to-navigate documents. Gather all
documentation for directives into one easy-to-reference guide, starting
with the former 'toctree' document. There are no changes to the content.
Signed-off-by: Stephen Finucane <stephen@that.guru>
These are going to form the basis of a future 'directive' document, so
we do some cleanup before this happens. There are a number of cleanup
items.
- Some paragraphs are reworded or clarified
- Semantic markup is added where possible
- Everything is wrapped to ~80 characters
Signed-off-by: Stephen Finucane <stephen@that.guru>
These are very poorly documented at present, especially given their
power and use in basically all non-Napoleon based Python documentation.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This is essentially the 'markup/inline' with a few small fixes. There
are also some modifications to the basic rST guide to highlight what a
role is; we were doing this for directives but not roles.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This is taken from the existing 'rest' documents. Little to no
modifications are necessary, thankfully.
Signed-off-by: Stephen Finucane <stephen@that.guru>
We don't currently care if a commit changes our coverage metrics, so we
can disable the status checks that would enforce that.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Fixes: #4738
This is simply the former 'tutorial' document renamed. A number of
references need to be updated, so this is done.
Signed-off-by: Stephen Finucane <stephen@that.guru>
We're going to use this document as the basis for a future usage
document, so we start by cleaning things up beforehand. A couple of
changes are necessary:
- The installation guide is referenced, rather than duplicating the
steps
In addition, there is a number of cleanup items.
- Some paragraphs are reworded or clarified
- Semantic markup is added where possible
- Everything is wrapped to ~80 characters
A number of TODOs are inserted. These will be resolved separately.
Signed-off-by: Stephen Finucane <stephen@that.guru>
We may want to eventually deprecate these in favour of 'tox', but this
cleans things up a little until then.
Signed-off-by: Stephen Finucane <stephen@that.guru>
These have been deprecated for a while and can now be removed.
Some indentation is also fixed, while we're at it.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Start structuring our docs a little better starting with a usage guide.
There are a number of changes happening here. We're going to start with
the installation guide, which is simply moved to the appropriate
subdirectory.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This is a large rework of the installation guide. There are a couple of
changes necessary:
- 'Mac OSX' is replaced by 'macOS'
- PyPI installation steps are moved to their own section
- Instructions are no longer provided for installing Python on Windows:
instead, we refer to the other, better-maintained guides.
In addition, there are a number of cleanup items.
- Some paragraphs are reworded or clarified
- Semantic markup is added where possible
- Everything is wrapped to ~80 characters
A number of TODOs are inserted. These will be resolved separately.
Signed-off-by: Stephen Finucane <stephen@that.guru>
We don't want to install this as a system plugin. Now that flake8 3.5.0
is in the wild, we can use this.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Fixes: #4492
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
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>
distutils/__init__.py:4: DeprecationWarning: the imp module is
deprecated in favour of importlib; see the module's documentation
for alternative uses
import imp
Signed-off-by: Stephen Finucane <stephen@that.guru>
As with the Makefile previously, these are not necessary now that we're
not printing anything different for various builders.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Most of these are not necessary now that we're not printing different
messages for various builders.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This allows builders to emit a final epilog message containing
information such as where resulting files can be found. This is only
emitted if the build was successful.
This allows us to remove this content from the 'make_mode' tool and
the legacy 'Makefile' and 'make.bat' templates. There's room for more
dramatic simplification of the former, but this will come later.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Given that we install Sphinx as part of the dependencies, there's no
reason to do it twice. Skip that step.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Given that we install Sphinx as part of the dependencies, there's no
reason to do it twice. Skip that step.
Signed-off-by: Stephen Finucane <stephen@that.guru>
There's an issue with 'pkgutils' and namespace packages. This has been
reported against setuptools [1], but until this is resolved, we simply
need to live with it. Ensure said warnings are filtered from tox too and
remove some unnecessary ones.
[1] https://github.com/pypa/setuptools/issues/1111
Signed-off-by: Stephen Finucane <stephen@that.guru>
This is no longer necessary. One test needs to be modified to deal with
how 'python -m pytest' modifies the PATH.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This is the recommended way to do pre-session configuration in pytest if
not using session fixtures [1].
With this, we're able to remove the custom 'test/run.py' script in its
entirety and run 'pytest' like everyone else does. We'll do this
separately to keep things simple.
[1] https://stackoverflow.com/a/12600154/613428
Signed-off-by: Stephen Finucane <stephen@that.guru>
This will have already been handled by setuptools. If the user isn't
using this then they've dug their own grave.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Start installing Python dependencies and Sphinx itself as part of the
CircleCI job rather than expecting it to be done in the Docker
container. This ensures we will use the version of the packages for a
given commit.
This is the other half of sphinx-doc/docker-ci#1.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Add docs for '--module-first' option and 'SPHINX_APIDOC_OPTIONS'
environment variable. Per the closest thing we have to official man page
guidelines [1]:
ENVIRONMENT
lists all environment variables that affect the program or function
and how they affect it.
[1] https://linux.die.net/man/7/man-pages
Signed-off-by: Stephen Finucane <stephen@that.guru>
Fixes#2250
This appears to have been missed in commit 69d1dfaa. One could add an
alias for this to restore behavior, but no one has reported the issue
since Sphinx meaning this seems unnecessary.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Run 'coverage report' after a successful coverage run. There's enough
coverage-related stuff here at this point to warrant its own section.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Embrace the tox-ified future. This explicitly asks users to use a
virtualenv to stop them shooting themselves in the foot.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This allows us to validate and reuse the testing tools we use locally
for "gate" tests and moves us closer to the eventual goal of deprecating
the Makefile targets. This involves adding two new targets to the list
of default targets run by tox - docs and mypy.
Note that we don't use tox-travis because, wonderful though it may be,
configuring it to exclude as many of the tests as we want to exclude is
a little convoluted (we have a big test matrix).
Signed-off-by: Stephen Finucane <stephen@that.guru>
We're going to be adding additional badges to this but, before we do
that, we should improve the README and remove a lot of the duplication
that has built up here.
The 'long_description' from 'setup.py' is moved into the README as there
is serious value in displaying this on GitHub, as much as there is value
in including the badges and other content from README.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Place configuration of the package itself first in the file, followed by
configuration of other tools.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Enabling coverage results in an increase in runtime, and while this may
be an acceptable compromise for some developers, it's not necessarily
something we need to run all the time. Move it to a separate target so
it can be run only by those who wish to use it.
Signed-off-by: Stephen Finucane <stephen@that.guru>
While there are already some skips included here, they clearly aren't
doing their job and the test fail locally. Resolve this.
Signed-off-by: Stephen Finucane <stephen@that.guru>
We are using this in our testing and actually need it for the flake8
plugin, so include this in the list of 'test' requirements.
Signed-off-by: Stephen Finucane <stephen@that.guru>
'mock' is part of the standard library in Python 3 since Python 3.3.
However, it's found in 'unittest.mock' - not 'mock'. We should install
the version for PyPi in all cases to minimize differences between the
two. When Python 2.7 support is dropped, we can consider switching to
the standard library version.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Fixes#4284
This simplifies a common pattern used here. This does result in a change
in the output code from 1 to 2 for some cases, but this shouldn't be an
issue as we already emit 2 for any parser issues.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This is a little more flexible than the existing set up and makes
maximum use of argparse capabilities.
This has the side-effect of no longer including configuration for the
'sphinx.ext.todo' extension when said extension is not enabled.
Signed-off-by: Stephen Finucane <stephen@that.guru>
The 'd' and 'key' values are used on a single line. Move these outside
the function to allow us to do other things with this function.
Signed-off-by: Stephen Finucane <stephen@that.guru>
We were never really using this file for its specified purpose [1]. Now
that we have everything cleanly organized in 'setup.py', there really
isn't any reason to keep it around. Remove it.
[1] https://caremad.io/posts/2013/07/setup-vs-requirement/
Signed-off-by: Stephen Finucane <stephen@that.guru>
Simply installing packages will ensure that most of the dependencies in
'setup.py' are installed, meaning 'test-reqs.txt' need only contain
those necessary for testing.
The only notable change is that the 'simplejson' module is dropped from
the requirements list. This included as a dependency for the PyPy
target, but it appears that this is not necessary today (though it may
have been when the target was added in 2011).
This retains 'setup.py test' which, as noted in the tox docs [1], is
sometimes expected for downstream distribution testing. We may wish to
find a way to synchronize requirements between 'test-reqs.txt' and this
section in the future, but that's work for another day.
[1] https://tox.readthedocs.io/en/latest/example/basic.html#integration-with-setup-py-test-command
Signed-off-by: Stephen Finucane <stephen@that.guru>
This version is silly old and anyone that's _still_ using this is not
going to be building Sphinx from source. Simply remove it.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Once again, not much different to the previous conversions. We make best
use of the argparse module, allowing us to remove some funky
workarounds.
Signed-off-by: Stephen Finucane <stephen@that.guru>
For the same reasons as the 'sphinx-apidoc' and 'sphinx-autogen' moves.
As before, we also take the opportunity to add a help string.
Signed-off-by: Stephen Finucane <stephen@that.guru>
For the same reasons as the 'sphinx-apidoc' move. We also take the
opportunity to add a help string and epilog while we're at it.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Another mostly trivial conversion. The only odd thing here is that we
add a '--version' parameter to keep things in line with the other
applications.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This lets us better reason about what the parser is doing and use tools
like 'sphinx-contrib.autoprogram' in our own documentation in the
future.
Signed-off-by: Stephen Finucane <stephen@that.guru>
This is pretty self-explanatory, with most changes coming about as a
side-effect of argparse vs. optparse API differences.
Lowercase characters are used in help strings, per argparse conventions.
Some tests are converted because argparse natively supports unicode.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Executable scripts without the '.py' extension are already created and
installed by setuptools, by way of the 'console_scripts' section. These
scripts are unnecessary noise. If people want to test this behavior
locally, use a virtualenv.
Signed-off-by: Stephen Finucane <stephen@that.guru>
There are still a couple of checks here but all of them can be removed
now:
- Check if using valid Python syntax
- Check if line length too long
- Check if using 'x == None/True/False'
- Check if using old HTML 3 tags
The first three are already handled by default by the 'flake8' tool. The
last one isn't replaced by anything, but it really isn't worth worrying
about now because the tags it checks for have been dead for a really
long time and would not be used by anyone writing HTML in the last 10
years. Combined, it means we can remove the entire file.
The 'style-check' target is updated to simply alias 'flake8'. It can be
removed in a future release. This allows us to stop using this target in
the Travis jobs, seeing as we already run flake8.
Signed-off-by: Stephen Finucane <stephen@that.guru>
If we want to check style, we run 'tox -e flake8': it shouldn't be
necessary to run some obscure 'make' command too. Make this possible by
moving the sole useful test from the target of this make command to a
flake8 plugin.
This includes a fix for a header that was previously excluded from
checks, but is now included.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Stephen Finucane