In Python 3, the default encoding of source files is utf-8. The encoding
cookie is now unnecessary and redundant so remove it. For more details,
see the docs:
https://docs.python.org/3/howto/unicode.html#the-string-type
> The default encoding for Python source code is UTF-8, so you can
> simply include a Unicode character in a string literal ...
Includes a fix for the flake8 header checks to stop expecting an
encoding cookie.
The open() function opens files in read-only text mode by default. Drop
the mode argument to be slightly simpler and more idiomatic.
https://docs.python.org/3/library/functions.html#open
> The default mode is 'r' (open for reading text, synonym of 'rt').
typed-ast has been a required dependency of mypy since v0.470. Can rely
on it being installed as a transient dependency and not list it
explicitly. For the change in mypy, see:
a207754a7e
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
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>
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
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>
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>
We're going to move the executable's here (or at least those that part
of the core library). The 'sphinx-build' executable was already moved,
so lets do 'sphinx-quickstart' next.
To avoid breaking packages that are using this feature directly, aliases
for the old 'main' method are included. This is based on what Django
does [1] and, like Django, will allow us to safely remove the old
modules in Sphinx 2.0.
[1] https://github.com/django/django/blob/1.11/django/test/runner.py#L688-L695
Signed-off-by: Stephen Finucane <stephen@that.guru>
We have multiple executables in tree and, while 'sphinx-build' is
arguably the most important of these, there's no reason its importance
should warrant inclusion at the package level.
Create a new module, 'sphinx.cmd', and move the code from
'sphinx.__init__' into a 'build' submodule within. This name might be a
bit disingenuous at present, given the availability of 'make-mode' here
too, but that's an artifact of the current executable design and can be
cleaned up later.
To avoid breaking packages that are using this feature directly, aliases
for the old 'main' method are included. This is based on what Django
does [1] and, like Django, will allow us to safely remove the old
modules in Sphinx 2.0.
[1] https://github.com/django/django/blob/1.11/django/test/runner.py#L688-L695
Signed-off-by: Stephen Finucane <stephen@that.guru>
The 'sphinx-apidoc' tool is no longer the only kid on the block when it
comes to automatic documentation of Python projects, with the likes of
'sphinx-autoapi' in development [1], and is not really maintained. Given
the fact that the tool is tangential to Sphinx's main goal, there isn't
really anything that warrants its continue existence as a core module.
Signify this by moving the feature to 'ext'. This allows the feature to
continue to exist in the package, but indicates that stability might be
worse than one would expect from the core library.
To avoid breaking packages that are using this feature directly, such as
pbr [3], aliases for the old 'main' method are included. This is based
on what Django does and, like Django, will allow us to safely remove the
old modules in Sphinx 2.0.
[1] https://github.com/rtfd/sphinx-autoapi
[2] https://github.com/sphinx-doc/sphinx/pull/3485#issuecomment-288081223
[3] https://github.com/django/django/blob/1.11/django/test/runner.py#L688-L695
Signed-off-by: Stephen Finucane <stephen@that.guru>
So far, sphinx generates the grammar files on demand.
It causes uninstallation does not remove whole of files.
With this fix, Sphinx bundles the files in the package.
With some recent changes that are slightly backwards compatible, we were going
to bump the version of the RTD theme. We wanted to drop the current version
pattern for the semver scheme, but Sphinx's requirement on the RTD theme is
pinned at >=0.1,<0.2. For now, we're stuck releasing on the current scheme.
This relaxes the versioning requirement for the theme, with 2.0 being the
following release that could contain backwards incompatible API changes. We'd
likely wait to bump to 1.0 until the next Sphinx release, as to not break
experience for users.
Refs snide/sphinx_rtd_theme#244
With some recent changes that are slightly backwards compatible, we were going
to bump the version of the RTD theme. We wanted to drop the current version
pattern for the semver scheme, but Sphinx's requirement on the RTD theme is
pinned at >=0.1,<0.2. For now, we're stuck releasing on the current scheme.
This relaxes the versioning requirement for the theme, with 2.0 being the
following release that could contain backwards incompatible API changes. We'd
likely wait to bump to 1.0 until the next Sphinx release, as to not break
experience for users.
Refs snide/sphinx_rtd_theme#244
As the author of one of the new theme dependencies (`alabaster`), having a wholly unqualified requirement scared me a bit re: ability to make non-bugfix releases without downstream users' sites changing underneath them in unexpected (visual) ways without them consciously upgrading Sphinx versions.
`alabaster` uses semantic versioning so the lock reflects this.
For consistency, I also updated the other new theme dependency similarly, and made `babel` match its fellow non-theme dependencies in having an optimistic (vs semantic) version lock, but I can revert these changes if desired.
- Rename 'default' theme to 'classic'.
- rename `themes/default` to `themes/classic`
- add new `themes/default` theme that derives from 'classic' theme for compatibility.
- setup.py depends to 'alabaster' and 'rtd' theme.
- theming.py import and run `alabaster.get_path()` to append path for alabaster theme.
- theming.py also import and run `sphinx_rtd_theme.get_html_theme_path()` to append path.
- sphinx-quickstart will generate `html_theme = 'alabaster'`.
- If user use 'default', sphinx emit notice (WARNING) suggestion to use 'alabaster' or use 'classic'.
- add documentation for new alabaster and readthedoc theme and link to original pages:
- https://pypi.python.org/pypi/alabaster
- https://pypi.python.org/pypi/sphinx_rtd_theme
