IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Use declarative metadata

Browse Source 
- Move to pyproject.toml metadata
- Update references to `setup.py`
- Use pypa/build
- Update workflows and tooling
This commit is contained in:
Adam Turner 2022-04-16 21:38:39 +01:00
parent 5477ef6675
commit b347657809
11 changed files with 183 additions and 205 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/workflows/docutils-latest.yml vendored
View File

@ -21,8 +21,6 @@ jobs:
python-version: 3 python-version: 3
- name: Check Python version - name: Check Python version
run: python --version run: python --version
- name: Unpin docutils
run: sed -i -e "s/'docutils>=.*'/'docutils'/" setup.py
- name: Install graphviz - name: Install graphviz
run: sudo apt-get install graphviz run: sudo apt-get install graphviz
- name: Install dependencies - name: Install dependencies

2
.github/workflows/lint.yml vendored
View File

@ -20,6 +20,6 @@ jobs:
with: with:
python-version: 3 python-version: 3
- name: Install dependencies - name: Install dependencies
run: pip install -U tox run: python -m pip install -U tox pip
- name: Run Tox - name: Run Tox
run: tox -e ${{ matrix.tool }} run: tox -e ${{ matrix.tool }}

4
CHANGES
View File

@ -4,6 +4,10 @@ Release 5.2.0 (in development)
Dependencies Dependencies
------------ ------------
* #10356: Sphinx now uses declarative metadata with ``pyproject.toml`` to
create packages, using PyPA's ``build`` project as a build backend. Patch by
Adam Turner.
Incompatible changes Incompatible changes
-------------------- --------------------

33
MANIFEST.in
View File

@ -1,33 +0,0 @@
include README.rst
include LICENSE
include AUTHORS
include CHANGES
include CHANGES.old
include CODE_OF_CONDUCT
include CONTRIBUTING.rst
include EXAMPLES
include babel.cfg
include Makefile
include sphinx-autogen.py
include sphinx-build.py
include sphinx-quickstart.py
include sphinx-apidoc.py
include tox.ini
include sphinx/locale/.tx/config
include sphinx/py.typed
recursive-include sphinx/templates *
recursive-include sphinx/texinputs *
recursive-include sphinx/texinputs_win *
recursive-include sphinx/themes *
recursive-include sphinx/locale *.js *.pot *.po *.mo
recursive-include sphinx/search/non-minified-js *.js
recursive-include sphinx/search/minified-js *.js
recursive-include sphinx/ext/autosummary/templates *
recursive-include tests *
recursive-include utils *
recursive-include doc *
prune doc/_build
prune sphinx/locale/.tx

2
Makefile
View File

@ -74,7 +74,7 @@ covertest:
.PHONY: build .PHONY: build
build: build:
@$(PYTHON) setup.py build @$(PYTHON) -m build .
.PHONY: docs .PHONY: docs
docs: docs:

252
pyproject.toml
View File

@ -1,123 +1,135 @@
from setuptools import find_packages, setup [build-system]
requires = ["flit_core>=3.7"]
build-backend = "flit_core.buildapi"
import sphinx # project metadata
[project]
name = "Sphinx"
description = "Python documentation generator"
readme = "README.rst"
urls.Changelog = "https://www.sphinx-doc.org/en/master/changes.html"
urls.Code = "https://github.com/sphinx-doc/sphinx"
urls.Download = "https://pypi.org/project/Sphinx/"
urls.Homepage = "https://www.sphinx-doc.org/"
urls."Issue tracker" = "https://github.com/sphinx-doc/sphinx/issues"
license.text = "BSD"
requires-python = ">=3.6"
with open('README.rst', encoding='utf-8') as f: # Classifiers list: https://pypi.org/classifiers/
long_desc = f.read() classifiers = [
"Development Status :: 5 - Production/Stable",
"Environment :: Console",
"Environment :: Web Environment",
"Intended Audience :: Developers",
"Intended Audience :: Education",
"Intended Audience :: End Users/Desktop",
"Intended Audience :: Science/Research",
"Intended Audience :: System Administrators",
"License :: OSI Approved :: BSD License",
"Operating System :: OS Independent",
"Programming Language :: Python",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3 :: Only",
"Programming Language :: Python :: 3.6",
"Programming Language :: Python :: 3.7",
"Programming Language :: Python :: 3.8",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: Implementation :: CPython",
"Programming Language :: Python :: Implementation :: PyPy",
"Framework :: Setuptools Plugin",
"Framework :: Sphinx",
"Framework :: Sphinx :: Extension",
"Framework :: Sphinx :: Theme",
"Topic :: Documentation",
"Topic :: Documentation :: Sphinx",
"Topic :: Internet :: WWW/HTTP :: Site Management",
"Topic :: Printing",
"Topic :: Software Development",
"Topic :: Software Development :: Documentation",
"Topic :: Text Processing",
"Topic :: Text Processing :: General",
"Topic :: Text Processing :: Indexing",
"Topic :: Text Processing :: Markup",
"Topic :: Text Processing :: Markup :: HTML",
"Topic :: Text Processing :: Markup :: LaTeX",
"Topic :: Utilities",
]
dependencies = [
"sphinxcontrib-applehelp",
"sphinxcontrib-devhelp",
"sphinxcontrib-jsmath",
"sphinxcontrib-htmlhelp>=2.0.0",
"sphinxcontrib-serializinghtml>=1.1.5",
"sphinxcontrib-qthelp",
"Jinja2>=3.0",
"Pygments>=2.12",
"docutils>=0.14,<0.20",
"snowballstemmer>=2.0",
"babel>=2.9",
"alabaster>=0.7,<0.8",
"imagesize>=1.3",
"requests>=2.5.0",
"packaging>=21.0",
"importlib-metadata>=4.8; python_version < '3.10'",
"colorama>=0.4.5; sys_platform == 'win32'",
]
dynamic = ["version"]
setup( [project.optional-dependencies]
name='Sphinx', docs = [
version=sphinx.__version__, "sphinxcontrib-websupport",
url='https://www.sphinx-doc.org/', ]
download_url='https://pypi.org/project/Sphinx/', lint = [
license='BSD', "flake8>=3.5.0",
author='Georg Brandl', "flake8-comprehensions",
author_email='georg@python.org', "flake8-bugbear",
description='Python documentation generator', "isort",
long_description=long_desc, "mypy>=0.971",
long_description_content_type='text/x-rst', "sphinx-lint",
project_urls={ "docutils-stubs",
"Code": "https://github.com/sphinx-doc/sphinx", "types-typed-ast",
"Changelog": "https://www.sphinx-doc.org/en/master/changes.html", "types-requests",
"Issue tracker": "https://github.com/sphinx-doc/sphinx/issues", ]
}, test = [
zip_safe=False, "pytest>=4.6",
classifiers=[ "html5lib",
'Development Status :: 5 - Production/Stable', "typed_ast; python_version < '3.8'",
'Environment :: Console', "cython",
'Environment :: Web Environment', ]
'Intended Audience :: Developers',
'Intended Audience :: Education', [[project.authors]]
'Intended Audience :: End Users/Desktop', name = "Georg Brandl"
'Intended Audience :: Science/Research', email = "georg@python.org"
'Intended Audience :: System Administrators',
'License :: OSI Approved :: BSD License', [project.scripts]
'Operating System :: OS Independent', sphinx-build = "sphinx.cmd.build:main"
'Programming Language :: Python', sphinx-quickstart = "sphinx.cmd.quickstart:main"
'Programming Language :: Python :: 3', sphinx-apidoc = "sphinx.ext.apidoc:main"
'Programming Language :: Python :: 3 :: Only', sphinx-autogen = "sphinx.ext.autosummary.generate:main"
'Programming Language :: Python :: 3.6',
'Programming Language :: Python :: 3.7', [project.entry-points."distutils.commands"]
'Programming Language :: Python :: 3.8', build_sphinx = 'sphinx.setup_command:BuildDoc'
'Programming Language :: Python :: 3.9',
'Programming Language :: Python :: 3.10', [tool.flit.module]
'Programming Language :: Python :: Implementation :: CPython', name = "sphinx"
'Programming Language :: Python :: Implementation :: PyPy',
'Framework :: Setuptools Plugin', [tool.flit.sdist]
'Framework :: Sphinx', include = [
'Framework :: Sphinx :: Extension', "LICENSE",
'Framework :: Sphinx :: Theme', "AUTHORS",
'Topic :: Documentation', "CHANGES",
'Topic :: Documentation :: Sphinx', # Documentation
'Topic :: Internet :: WWW/HTTP :: Site Management', "doc/",
'Topic :: Printing', "CODE_OF_CONDUCT", # used as an include in the Documentation
'Topic :: Software Development', "EXAMPLES", # used as an include in the Documentation
'Topic :: Software Development :: Documentation', # Tests
'Topic :: Text Processing', "tests/",
'Topic :: Text Processing :: General', "tox.ini",
'Topic :: Text Processing :: Indexing', # Utilities
'Topic :: Text Processing :: Markup', "utils/",
'Topic :: Text Processing :: Markup :: HTML', "babel.cfg",
'Topic :: Text Processing :: Markup :: LaTeX', ]
'Topic :: Utilities', exclude = [
], "doc/_build",
platforms='any', ]
packages=find_packages(exclude=['tests', 'utils']),
package_data = {
'sphinx': ['py.typed'],
},
include_package_data=True,
entry_points={
'console_scripts': [
'sphinx-build = sphinx.cmd.build:main',
'sphinx-quickstart = sphinx.cmd.quickstart:main',
'sphinx-apidoc = sphinx.ext.apidoc:main',
'sphinx-autogen = sphinx.ext.autosummary.generate:main',
],
'distutils.commands': [
'build_sphinx = sphinx.setup_command:BuildDoc',
],
},
python_requires=">=3.6",
install_requires=[
'sphinxcontrib-applehelp',
'sphinxcontrib-devhelp',
'sphinxcontrib-jsmath',
'sphinxcontrib-htmlhelp>=2.0.0',
'sphinxcontrib-serializinghtml>=1.1.5',
'sphinxcontrib-qthelp',
'Jinja2>=3.0',
'Pygments>=2.12',
'docutils>=0.14,<0.20',
'snowballstemmer>=2.0',
'babel>=2.9',
'alabaster>=0.7,<0.8',
'imagesize>=1.3',
'requests>=2.5.0',
'packaging>=21.0',
"importlib-metadata>=4.8; python_version < '3.10'",
"colorama>=0.4.5; sys_platform == 'win32'",
],
extras_require={
'docs': [
'sphinxcontrib-websupport',
],
'lint': [
'flake8>=3.5.0',
'flake8-comprehensions',
'flake8-bugbear',
'isort',
'mypy>=0.971',
'sphinx-lint',
'docutils-stubs',
"types-typed-ast",
"types-requests",
],
'test': [
'pytest>=4.6',
'html5lib',
"typed_ast; python_version < '3.8'",
'cython',
],
},
)

11
setup.cfg
View File

@ -1,14 +1,3 @@
[metadata]
license_files = LICENSE
[egg_info]
tag_build = .dev
tag_date = true
[aliases]
release = egg_info -Db ''
upload = upload --sign --identity=36580288
[flake8] [flake8]
max-line-length = 95 max-line-length = 95
ignore = E116,E241,E251,E741,W504,I101,B006,B023 ignore = E116,E241,E251,E741,W504,I101,B006,B023

40
sphinx/__init__.py
View File

@ -1,13 +1,11 @@
"""The Sphinx documentation toolchain.""" """The Sphinx documentation toolchain."""
# Keep this file executable as-is in Python 3! # Keep this file executable as-is in Python 3!
# (Otherwise getting the version out of it from setup.py is impossible.) # (Otherwise getting the version out of it when packaging is impossible.)
import os import os
import subprocess
import warnings import warnings
from os import path from os import path
from subprocess import PIPE
from .deprecation import RemovedInNextVersionWarning from .deprecation import RemovedInNextVersionWarning
@ -21,8 +19,8 @@ warnings.filterwarnings('ignore', "'U' mode is deprecated",
warnings.filterwarnings('ignore', 'The frontend.Option class .*', warnings.filterwarnings('ignore', 'The frontend.Option class .*',
DeprecationWarning, module='docutils.frontend') DeprecationWarning, module='docutils.frontend')
__version__ = '5.2.0+' __version__ = '5.2.0'
__released__ = '5.2.0' # used when Sphinx builds its own docs __display_version__ = __version__ # used for command line version
#: Version info for better programmatic use. #: Version info for better programmatic use.
#: #:
@ -36,18 +34,22 @@ version_info = (5, 2, 0, 'beta', 0)
package_dir = path.abspath(path.dirname(__file__)) package_dir = path.abspath(path.dirname(__file__))
__display_version__ = __version__ # used for command line version _in_development = True
if __version__.endswith('+'): if _in_development:
# try to find out the commit hash if checked out from git, and append # Only import subprocess if needed
# it to __version__ (since we use this value from setup.py, it gets import subprocess
# automatically propagated to an installed copy as well)
__display_version__ = __version__
__version__ = __version__[:-1] # remove '+' for PEP-440 version spec.
try: try:
ret = subprocess.run(['git', 'show', '-s', '--pretty=format:%h'], ret = subprocess.run(
cwd=package_dir, ['git', 'show', '-s', '--pretty=format:%h'],
stdout=PIPE, stderr=PIPE, encoding='ascii') cwd=package_dir,
if ret.stdout: stdout=subprocess.PIPE,
__display_version__ += '/' + ret.stdout.strip() stderr=subprocess.PIPE,
except Exception: encoding='ascii',
pass ).stdout
if ret:
__display_version__ += '+/' + ret.strip()
del ret
finally:
del subprocess
del _in_development

8
tox.ini
View File

@ -1,6 +1,7 @@
[tox] [tox]
minversion = 2.4.0 minversion = 2.4.0
envlist = docs,flake8,mypy,twine,py{36,37,38,39,310},du{14,15,16,17,18,19} envlist = docs,flake8,mypy,twine,py{36,37,38,39,310},du{14,15,16,17,18,19}
isolated_build = True
[testenv] [testenv]
usedevelop = True usedevelop = True
@ -34,7 +35,7 @@ commands=
[testenv:du-latest] [testenv:du-latest]
commands = commands =
python -m pip install "git+https://repo.or.cz/docutils.git#subdirectory=docutils" python -m pip install "git+https://repo.or.cz/docutils.git#subdirectory=docutils" --no-warn-conflicts
{[testenv]commands} {[testenv]commands}
[testenv:flake8] [testenv:flake8]
@ -92,7 +93,7 @@ description =
Build documentation. Build documentation.
extras = extras =
docs docs
deps = deps =
sphinx-autobuild sphinx-autobuild
commands = commands =
sphinx-autobuild ./doc ./build/sphinx/ sphinx-autobuild ./doc ./build/sphinx/
@ -103,8 +104,9 @@ description =
Lint package. Lint package.
deps = deps =
twine twine
build
commands = commands =
python setup.py release bdist_wheel sdist python -m build .
twine check dist/* twine check dist/*
[testenv:bindep] [testenv:bindep]

26
utils/bump_version.py
View File

@ -23,19 +23,23 @@ def stringify_version(version_info, in_develop=True):
def bump_version(path, version_info, in_develop=True): def bump_version(path, version_info, in_develop=True):
version = stringify_version(version_info, in_develop) version = stringify_version(version_info, in_develop)
release = version
if in_develop:
version += '+'
with open(path, 'r+', encoding='utf-8') as f: with open(path, 'r', encoding='utf-8') as f:
body = f.read() lines = f.read().splitlines()
body = re.sub(r"(?<=__version__ = ')[^']+", version, body)
body = re.sub(r"(?<=__released__ = ')[^']+", release, body)
body = re.sub(r"(?<=version_info = )\(.*\)", str(version_info), body)
f.seek(0) for i, line in enumerate(lines):
f.truncate(0) if line.startswith('__version__ = '):
f.write(body) lines[i] = f"__version__ = '{version}'"
continue
if line.startswith('version_info = '):
lines[i] = f'version_info = {version_info}'
continue
if line.startswith('_in_development = '):
lines[i] = f'_in_development = {in_develop}'
continue
with open(path, 'w', encoding='utf-8') as f:
f.write('\n'.join(lines) + '\n')
def parse_version(version): def parse_version(version):

8
utils/release-checklist
View File

@ -10,7 +10,7 @@ for stable releases
* Check diff by ``git diff`` * Check diff by ``git diff``
* ``git commit -am 'Bump to X.Y.Z final'`` * ``git commit -am 'Bump to X.Y.Z final'``
* ``make clean`` * ``make clean``
* ``python setup.py release bdist_wheel sdist`` * ``python -m build .``
* ``twine upload dist/Sphinx-* --sign --identity [your GPG key]`` * ``twine upload dist/Sphinx-* --sign --identity [your GPG key]``
* open https://pypi.org/project/Sphinx/ and check there are no obvious errors * open https://pypi.org/project/Sphinx/ and check there are no obvious errors
* ``sh utils/bump_docker.sh X.Y.Z`` * ``sh utils/bump_docker.sh X.Y.Z``
@ -34,7 +34,7 @@ for first beta releases
* Check diff by ``git diff`` * Check diff by ``git diff``
* ``git commit -am 'Bump to X.Y.0 beta1'`` * ``git commit -am 'Bump to X.Y.0 beta1'``
* ``make clean`` * ``make clean``
* ``python setup.py release bdist_wheel sdist`` * ``python -m build .``
* ``twine upload dist/Sphinx-* --sign --identity [your GPG key]`` * ``twine upload dist/Sphinx-* --sign --identity [your GPG key]``
* open https://pypi.org/project/Sphinx/ and check there are no obvious errors * open https://pypi.org/project/Sphinx/ and check there are no obvious errors
* ``git tag vX.Y.0b1`` * ``git tag vX.Y.0b1``
@ -62,7 +62,7 @@ for other beta releases
* Check diff by ``git diff`` * Check diff by ``git diff``
* ``git commit -am 'Bump to X.Y.0 betaN'`` * ``git commit -am 'Bump to X.Y.0 betaN'``
* ``make clean`` * ``make clean``
* ``python setup.py release bdist_wheel sdist`` * ``python -m build .``
* ``twine upload dist/Sphinx-* --sign --identity [your GPG key]`` * ``twine upload dist/Sphinx-* --sign --identity [your GPG key]``
* open https://pypi.org/project/Sphinx/ and check there are no obvious errors * open https://pypi.org/project/Sphinx/ and check there are no obvious errors
* ``git tag vX.Y.0bN`` * ``git tag vX.Y.0bN``
@ -87,7 +87,7 @@ for major releases
* Check diff by ``git diff`` * Check diff by ``git diff``
* ``git commit -am 'Bump to X.Y.0 final'`` * ``git commit -am 'Bump to X.Y.0 final'``
* ``make clean`` * ``make clean``
* ``python setup.py release bdist_wheel sdist`` * ``python -m build .``
* ``twine upload dist/Sphinx-* --sign --identity [your GPG key]`` * ``twine upload dist/Sphinx-* --sign --identity [your GPG key]``
* open https://pypi.org/project/Sphinx/ and check there are no obvious errors * open https://pypi.org/project/Sphinx/ and check there are no obvious errors
* ``sh utils/bump_docker.sh X.Y.Z`` * ``sh utils/bump_docker.sh X.Y.Z``