helloworld:
- Return version metadata from extension
- Use 'reST' instead of 'rST'
- Don't use single backticks
todo:
- Return version metadata from extension
- Link to events section of API guide, rather than entire document
- Include name of phases in when describing build phases
- Use more method cross-references where possible
- Fix typo in usage example
recipe:
- Return version metadata from extension
- Rework code to simplify things
- Remove docstrings from 'generate' functions, which are simply
duplicates of the original docstring
- Rename 'rcp' directive to 'recipe', the 'reref' role to 'ref', and a
whole lot of variables to something more grokable
- Fix typos in both documentation and code
I've also fixed up the docstrings for some of the 'domain' functions to
make them render a little nicer (they took me a while to figure out).
Signed-off-by: Stephen Finucane <stephen@that.guru>
Adopt the same format as was recently added in the "hello world"
tutorial, making this more of a walkthrough as expected from tutorials.
Signed-off-by: Stephen Finucane <stephen@that.guru>
The bindep (BINary DEPendency automation) tool is a tool for checking
the presence of binary packages needed to use an application / library.
Use it to specify the dependencies needed to successfully pass the LaTex
tests. Only Fedora targets are currently provided.
Signed-off-by: Stephen Finucane <stephen@that.guru>
There were two used:
- print_function
- absolute_import
Both of these are mandatory in Python 3.0 onwards [1] and can therefore
be removed...mostly. Unfortunately, mypy is still running in Python 2.7
mode, meaning we need the 'print_function' future wherever we're calling
'print' with the 'file' argument. There's also a single
'absolute_import' future that must be retained as its removal breaks a
test for as-yet unknown reasons. TODOs are added to resolve both issues
in the future.
[1] https://docs.python.org/3/library/__future__.html
Signed-off-by: Stephen Finucane <stephen@that.guru>
This one is a little unusual. The current theming doc mixes user-focused
documentation with developer-focused documentation. This is confusing
and unnecessary. Resolve the issue by splitting the doc in two. The
user-focused docs are moved to the advanced section of the usage guide,
while the developer docs remain where they are, pending the addition of
a developer guide.
Signed-off-by: Stephen Finucane <stephen@that.guru>
- 'logger' was unused and can be removed
- 'TextTranslator.sectionchars' was overridden in '__init__' and doesn't
need to be defined
Signed-off-by: Stephen Finucane <stephen@that.guru>
As with tox and make before it, we run everything that we can against
Python 3 (Python 3.6 in this case).
Signed-off-by: Stephen Finucane <stephen@that.guru>
As with the tox change, it makes sense to test things against Python 3
by default now, seeing as that will be the only version supported in
Sphinx 2.0.
Signed-off-by: Stephen Finucane <stephen@that.guru>
The demise of Python 2.7 is not far off and we intend to drop support
for it in Sphinx 2.0. As a result, there probably isn't a better time
than now to start testing with Python 3 by default. There are a couple
of advantages to this:
- flake8 is stricter under Python 3 and we don't need to ignore files
with Python 3 syntax
- We get to dogfood Sphinx against its own documentation using Python 3
- pylint gains support for Python 3 syntax
Signed-off-by: Stephen Finucane <stephen@that.guru>
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>
Stephen Finucane