Skip to content

Commit 70fb13c

Browse files
pradyunsgpradyunsg
authored
Merge pull request #763 from webknjaz/maintenance/sphinx-setup
⚙ Refactor the sphinx setup
2 parents 5409b68 + 5e7c767 commit 70fb13c

15 files changed

Lines changed: 142 additions & 121 deletions

‎noxfile.py‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,19 +10,31 @@
1010
@nox.session(py="3")
1111
def build(session, autobuild=False):
1212
session.install("-r", "requirements.txt")
13-
# Treat warnings as errors.
14-
session.env["SPHINXOPTS"] = "-W"
1513

16-
shutil.rmtree("build", ignore_errors=True)
14+
target_build_dir = "build"
15+
16+
shutil.rmtree(target_build_dir, ignore_errors=True)
1717

1818
if autobuild:
1919
command = "sphinx-autobuild"
2020
extra_args = "-H", "0.0.0.0"
2121
else:
2222
command = "sphinx-build"
23-
extra_args = ()
24-
25-
session.run(command, *extra_args, "-W", "-b", "html", "source", "build")
23+
extra_args = (
24+
"--color", # colorize the output, unsupported by autobuild
25+
)
26+
27+
session.run(
28+
command, *extra_args,
29+
# FIXME: uncomment once the theme is fixed
30+
# Ref: https://github.com/pypa/pypa-docs-theme/issues/17
31+
# "-j", "auto", # parallelize the build
32+
"-b", "html", # use HTML builder
33+
"-n", # nitpicky warn about all missing references
34+
"-W", # Treat warnings as errors.
35+
"source", # where the rst files are located
36+
target_build_dir, # where to put the html output
37+
)
2638

2739

2840
@nox.session(py="3")

‎requirements.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
sphinx==2.1.2
1+
sphinx==3.2.0
22
sphinx-autobuild==0.7.1
33
git+https://github.com/python/python-docs-theme.git#egg=python-docs-theme
44
git+https://github.com/pypa/pypa-docs-theme.git#egg=pypa-docs-theme

‎source/conf.py‎

Lines changed: 39 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
3232
# ones.
3333
extensions = [
34+
'sphinx.ext.extlinks',
3435
'sphinx.ext.intersphinx',
3536
'sphinx.ext.todo',
3637
]
@@ -51,9 +52,19 @@
5152
# The master toctree document.
5253
master_doc = 'index'
5354

55+
# -- Project information -----------------------------------------------------
56+
57+
github_url = 'https://github.com'
58+
github_repo_org = 'pypa'
59+
github_repo_name = 'packaging.python.org'
60+
github_repo_slug = f'{github_repo_org}/{github_repo_name}'
61+
github_repo_url = f'{github_url}/{github_repo_slug}'
62+
github_repo_issues_url = f'{github_url}/{github_repo_slug}/issues'
63+
github_sponsors_url = f'{github_url}/sponsors'
64+
5465
# General information about the project.
5566
project = u'Python Packaging User Guide'
56-
copyright = u'2013–2019, PyPA'
67+
copyright = u'2013–2020, PyPA'
5768
author = 'Python Packaging Authority'
5869

5970
# The version info for the project you're documenting, acts as replacement for
@@ -88,8 +99,8 @@
8899

89100
# The reST default role (used for this markup: `text`) to use for all
90101
# documents.
91-
#
92-
# default_role = None
102+
# Ref: python-attrs/attrs#571
103+
default_role = 'any' # makes single backticks autofind targets
93104

94105
# If true, '()' will be appended to :func: etc. cross-reference text.
95106
#
@@ -132,7 +143,7 @@
132143
'collapsiblesidebar': True,
133144
'externalrefs': True,
134145
'navigation_depth': 2,
135-
'issues_url': 'https://github.com/pypa/python-packaging-user-guide/issues'
146+
'issues_url': github_repo_issues_url,
136147
}
137148

138149
# Add any paths that contain custom themes here, relative to this directory.
@@ -350,9 +361,19 @@
350361
#
351362
# texinfo_no_detailmenu = False
352363

364+
# -- Options for extlinks extension ---------------------------------------
365+
extlinks = {
366+
'issue': (f'{github_repo_issues_url}/%s', '#'), # noqa: WPS323
367+
'pr': (f'{github_repo_url}/pull/%s', 'PR #'), # noqa: WPS323
368+
'commit': (f'{github_repo_url}/commit/%s', ''), # noqa: WPS323
369+
'gh': (f'{github_url}/%s', 'GitHub: '), # noqa: WPS323
370+
'user': (f'{github_sponsors_url}/%s', '@'), # noqa: WPS323
371+
}
372+
353373
# Example configuration for intersphinx: refer to the Python standard library.
354374
intersphinx_mapping = {
355-
'python': ('https://docs.python.org/3.6', None),
375+
'python': ('https://docs.python.org/3', None),
376+
'python2': ('https://docs.python.org/2', None),
356377
'pip': ('https://pip.pypa.io/en/latest/', None),
357378
}
358379

@@ -362,30 +383,16 @@
362383

363384
todo_include_todos = True
364385

365-
# Configure the GitHub PR role to point to our project.
366-
367-
pr_role_github_org_and_project = 'pypa/python-packaging-user-guide'
368-
369-
#
370-
# Custom plugin code below.
371-
#
372-
373-
374-
def setup(app):
375-
app.add_config_value('pr_role_github_org_and_project', None, 'html')
376-
app.add_role('pr', pr_role)
377-
378-
379-
def pr_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
380-
"""Transforms ':pr:`number`'' to a hyperlink to the referenced pull request
381-
on GitHub."""
382-
from docutils import nodes
383-
384-
app = inliner.document.settings.env
385-
project = app.config.pr_role_github_org_and_project
386-
title = '#{}'.format(text)
387-
388-
uri = 'https://github.com/{}/pull/{}'.format(project, text)
389-
rn = nodes.reference(
390-
title, title, internal=False, refuri=uri, classes=['pr'])
391-
return [rn], []
386+
nitpicky = True
387+
388+
# NOTE: consider having a separate ignore file
389+
# Ref: https://stackoverflow.com/a/30624034/595220
390+
nitpick_ignore = [
391+
('envvar', 'PATH'),
392+
('py:func', 'find_packages'),
393+
('py:func', 'pkg_resources.iter_entry_points'),
394+
('py:func', 'setup'),
395+
('py:func', 'setuptools.find_namespace_packages'),
396+
('py:func', 'setuptools.find_packages'),
397+
('py:func', 'setuptools.setup'),
398+
]

‎source/discussions/pip-vs-easy-install.rst‎

Lines changed: 39 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -21,45 +21,45 @@ environments.
2121

2222
Here's a breakdown of the important differences between pip and easy_install now:
2323

24-
+------------------------------+----------------------------------+-------------------------------+
25-
| | **pip** | **easy_install** |
26-
+------------------------------+----------------------------------+-------------------------------+
27-
|Installs from :term:`Wheels |Yes |No |
28-
|<Wheel>` | | |
29-
+------------------------------+----------------------------------+-------------------------------+
30-
|Uninstall Packages |Yes (``pip uninstall``) |No |
31-
+------------------------------+----------------------------------+-------------------------------+
32-
|Dependency Overrides |Yes (:ref:`Requirements Files |No |
33-
| |<pip:Requirements Files>`) | |
34-
+------------------------------+----------------------------------+-------------------------------+
35-
|List Installed Packages |Yes (``pip list`` and ``pip |No |
36-
| |freeze``) | |
37-
+------------------------------+----------------------------------+-------------------------------+
38-
|:pep:`438` |Yes |No |
39-
|Support | | |
40-
+------------------------------+----------------------------------+-------------------------------+
41-
|Installation format |'Flat' packages with `egg-info` | Encapsulated Egg format |
42-
| |metadata. | |
43-
+------------------------------+----------------------------------+-------------------------------+
44-
|sys.path modification |No |Yes |
45-
| | | |
46-
| | | |
47-
+------------------------------+----------------------------------+-------------------------------+
48-
|Installs from :term:`Eggs |No |Yes |
49-
|<Egg>` | | |
50-
+------------------------------+----------------------------------+-------------------------------+
51-
|`pylauncher support`_ |No |Yes [1]_ |
52-
| | | |
53-
+------------------------------+----------------------------------+-------------------------------+
54-
|:ref:`Multi-version Installs` |No |Yes |
55-
| | | |
56-
+------------------------------+----------------------------------+-------------------------------+
57-
|Exclude scripts during install|No |Yes |
58-
| | | |
59-
+------------------------------+----------------------------------+-------------------------------+
60-
|per project index |Only in virtualenv |Yes, via setup.cfg |
61-
| | | |
62-
+------------------------------+----------------------------------+-------------------------------+
24+
+------------------------------+--------------------------------------+-------------------------------+
25+
| | **pip** | **easy_install** |
26+
+------------------------------+--------------------------------------+-------------------------------+
27+
|Installs from :term:`Wheels |Yes |No |
28+
|<Wheel>` | | |
29+
+------------------------------+--------------------------------------+-------------------------------+
30+
|Uninstall Packages |Yes (``pip uninstall``) |No |
31+
+------------------------------+--------------------------------------+-------------------------------+
32+
|Dependency Overrides |Yes (:ref:`Requirements Files |No |
33+
| |<pip:Requirements Files>`) | |
34+
+------------------------------+--------------------------------------+-------------------------------+
35+
|List Installed Packages |Yes (``pip list`` and ``pip |No |
36+
| |freeze``) | |
37+
+------------------------------+--------------------------------------+-------------------------------+
38+
|:pep:`438` |Yes |No |
39+
|Support | | |
40+
+------------------------------+--------------------------------------+-------------------------------+
41+
|Installation format |'Flat' packages with :file:`egg-info` | Encapsulated Egg format |
42+
| |metadata. | |
43+
+------------------------------+--------------------------------------+-------------------------------+
44+
|sys.path modification |No |Yes |
45+
| | | |
46+
| | | |
47+
+------------------------------+--------------------------------------+-------------------------------+
48+
|Installs from :term:`Eggs |No |Yes |
49+
|<Egg>` | | |
50+
+------------------------------+--------------------------------------+-------------------------------+
51+
|`pylauncher support`_ |No |Yes [1]_ |
52+
| | | |
53+
+------------------------------+--------------------------------------+-------------------------------+
54+
|:ref:`Multi-version Installs` |No |Yes |
55+
| | | |
56+
+------------------------------+--------------------------------------+-------------------------------+
57+
|Exclude scripts during install|No |Yes |
58+
| | | |
59+
+------------------------------+--------------------------------------+-------------------------------+
60+
|per project index |Only in virtualenv |Yes, via setup.cfg |
61+
| | | |
62+
+------------------------------+--------------------------------------+-------------------------------+
6363

6464
----
6565

‎source/glossary.rst‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Glossary
2727
Distribution Package
2828

2929
A versioned archive file that contains Python :term:`packages <Import
30-
Package>`, :term:`modules <module>`, and other resource files that are
30+
Package>`, :term:`modules <Module>`, and other resource files that are
3131
used to distribute a :term:`Release`. The archive file is what an
3232
end-user will download from the internet and install.
3333

@@ -49,7 +49,7 @@ Glossary
4949

5050
Extension Module
5151

52-
A :term:`module` written in the low-level language of the Python implementation:
52+
A :term:`Module` written in the low-level language of the Python implementation:
5353
C/C++ for Python, Java for Jython. Typically contained in a single
5454
dynamically loadable pre-compiled file, e.g. a shared object (.so) file
5555
for Python extensions on Unix, a DLL (given the .pyd extension) for
@@ -121,8 +121,8 @@ Glossary
121121

122122
Pure Module
123123

124-
A :term:`module` written in Python and contained in a single `.py` file (and
125-
possibly associated `.pyc` and/or `.pyo` files).
124+
A :term:`Module` written in Python and contained in a single ``.py`` file (and
125+
possibly associated ``.pyc`` and/or ``.pyo`` files).
126126

127127

128128
Python Packaging Authority (PyPA)
@@ -147,12 +147,12 @@ Glossary
147147

148148
`pypi.org <https://pypi.org>`_ is the domain name for the
149149
:term:`Python Package Index (PyPI)`. It replaced the legacy index
150-
domain name, `pypi.python.org`, in 2017. It is powered by
150+
domain name, ``pypi.python.org``, in 2017. It is powered by
151151
:ref:`warehouse`.
152152

153153
pyproject.toml
154154

155-
The tool-agnostic :term:`project` specification file.
155+
The tool-agnostic :term:`Project` specification file.
156156
Defined in :pep:`518`.
157157

158158
Release

‎source/guides/distributing-packages-using-setuptools.rst‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -815,10 +815,10 @@ To build the wheel:
815815
python setup.py bdist_wheel
816816

817817

818-
`bdist_wheel` will detect that the code is pure Python, and build a wheel that's
819-
named such that it's usable on any Python installation with the same major
820-
version (Python 2 or Python 3) as the version you used to build the wheel. For
821-
details on the naming of wheel files, see :pep:`425`.
818+
``bdist_wheel`` will detect that the code is pure Python, and build a wheel
819+
that's named such that it's usable on any Python installation with the same
820+
major version (Python 2 or Python 3) as the version you used to build the
821+
wheel. For details on the naming of wheel files, see :pep:`425`.
822822

823823
If your code supports both Python 2 and 3, but with different code (e.g., you
824824
use `"2to3" <https://docs.python.org/2/library/2to3.html>`_) you can run
@@ -842,9 +842,9 @@ To build the wheel:
842842
python setup.py bdist_wheel
843843

844844

845-
`bdist_wheel` will detect that the code is not pure Python, and build a wheel
846-
that's named such that it's only usable on the platform that it was built
847-
on. For details on the naming of wheel files, see :pep:`425`.
845+
:command:`bdist_wheel` will detect that the code is not pure Python, and build
846+
a wheel that's named such that it's only usable on the platform that it was
847+
built on. For details on the naming of wheel files, see :pep:`425`.
848848

849849
.. note::
850850

‎source/guides/dropping-older-python-versions.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,9 @@ Examples::
4646
Requires-Python: ">=3"
4747
Requires-Python: ">2.7,!=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
4848

49-
The way to set those values is within the call to `setup` within your setup.py script. This will insert the Requires-Python
50-
metadata values based on the argument you provide in `python_requires`.
49+
The way to set those values is within the call to ``setup`` within your
50+
:file:`setup.py` script. This will insert the ``Requires-Python``
51+
metadata values based on the argument you provide in ``python_requires``.
5152

5253
.. code-block:: python
5354

‎source/guides/installing-scientific-packages.rst‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Starting with version 1.10.4 of NumPy and version 1.0.0 of SciPy, pre-built
2323
32-bit and 64-bit binaries in the ``wheel`` format are available for all major
2424
operating systems (Windows, macOS, and Linux) on PyPI. Note, however, that on
2525
Windows, NumPy binaries are linked against the `ATLAS
26-
<http://www.netlib.org/atlas/>` BLAS/LAPACK library, restricted to SSE2
26+
<http://www.netlib.org/atlas/>`__ BLAS/LAPACK library, restricted to SSE2
2727
instructions, so they may not provide optimal linear algebra performance.
2828

2929
There are a number of alternative options for obtaining scientific Python
@@ -76,8 +76,8 @@ environments. Allowing access to distributions installed into the system Python
7676
when using virtual environments is a common approach to working around this
7777
limitation.
7878

79-
The `wheel` project also provides a `wheel convert` subcommand that can
80-
convert a Windows `bdist_wininst` installer to a wheel.
79+
The :term:`Wheel` project also provides a :command:`wheel convert` subcommand that can
80+
convert a Windows :command:`bdist_wininst` installer to a wheel.
8181

8282
.. preserve old links to this heading
8383
.. _mac-os-x-installers-and-package-managers:
@@ -142,6 +142,6 @@ packages, it is not limited to just Python packages. It has full support for
142142
native virtual environments. Conda makes environments first-class citizens,
143143
making it easy to create independent environments even for C libraries. It is
144144
written in Python, but is Python-agnostic. Conda manages Python itself as a
145-
package, so that `conda update python` is possible, in contrast to pip, which
146-
only manages Python packages. Conda is available in Anaconda and Miniconda (an
147-
easy-to-install download with just Python and conda).
145+
package, so that :command:`conda update python` is possible, in contrast to
146+
pip, which only manages Python packages. Conda is available in Anaconda and
147+
Miniconda (an easy-to-install download with just Python and conda).

‎source/guides/migrating-to-pypi-org.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
Migrating to PyPI.org
44
=====================
55

6-
:term:`PyPI.org` is the new, rewritten version of PyPI that has replaced the
6+
:term:`pypi.org` is the new, rewritten version of PyPI that has replaced the
77
legacy PyPI code base. It is the default version of PyPI that people are
88
expected to use. These are the tools and processes that people will need to
99
interact with ``PyPI.org``.

‎source/guides/using-testpypi.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
Using TestPyPI
55
==============
66

7-
`TestPyPI` is a separate instance of the :term:`Python Package Index (PyPI)`
7+
``TestPyPI`` is a separate instance of the :term:`Python Package Index (PyPI)`
88
that allows you to try out the distribution tools and process without worrying
99
about affecting the real index. TestPyPI is hosted at
1010
`test.pypi.org <https://test.pypi.org>`_

0 commit comments

Comments
 (0)