Skip to content

Commit 5c51b93

Browse files
didi
authored
Merge branch 'master' into organize-guides-index
2 parents 83c2b20 + 453701c commit 5c51b93

31 files changed

Lines changed: 1139 additions & 378 deletions

‎README.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,9 @@ Code of Conduct
1414

1515
Everyone interacting in the Python Packaging User Guide project's codebases,
1616
issue trackers, chat rooms, and mailing lists are expected to follow the
17-
`PyPA Code of Conduct`_.
17+
`PSF Code of Conduct`_.
1818

19-
.. _PyPA Code of Conduct: https://www.pypa.io/en/latest/code-of-conduct/
19+
.. _PSF Code of Conduct: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md
2020

2121
Contributing
2222
------------

‎noxfile.py‎

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,17 +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"
20+
extra_args = "-H", "0.0.0.0"
2021
else:
2122
command = "sphinx-build"
22-
23-
session.run(command, "-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+
)
2438

2539

2640
@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: 41 additions & 34 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.
@@ -185,8 +196,8 @@
185196

186197
# Custom sidebar templates, filenames relative to this file.
187198
html_sidebars = {
188-
'**': ['localtoc.html', 'relations.html'],
189-
'index': ['localtoc.html']
199+
'**': ['globaltoc.html', 'relations.html'],
200+
'index': ['globaltoc.html']
190201
}
191202

192203
# Additional templates that should be rendered to pages, maps page names to
@@ -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/contribute.rst‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,10 @@ the guide, please read the :ref:`style guide <contributing_style_guide>`.
2121
.. __: https://github.com/pypa/python-packaging-user-guide/issues
2222
.. __: https://github.com/pypa/python-packaging-user-guide/pulls
2323

24-
By contributing to the |PyPUG|, you're expected to follow the Python Packaging
25-
Authority's `Contributor Code of Conduct`__. Harassment, personal attacks, and
26-
other unprofessional conduct is not acceptable.
24+
By contributing to the |PyPUG|, you're expected to follow the PSF's
25+
`Code of Conduct`__.
2726

28-
.. __: https://www.pypa.io/en/latest/code-of-conduct/
27+
.. __: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md
2928

3029

3130
Documentation types
@@ -64,7 +63,7 @@ Specifications
6463
--------------
6564

6665
Specifications are reference documention focused on comprehensively documenting
67-
an agreed-upon iterface for interoperability between packaging tools.
66+
an agreed-upon interface for interoperability between packaging tools.
6867
:doc:`example specification-style document <specifications/core-metadata>`.
6968

7069

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

Lines changed: 42 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,12 @@ pip vs easy_install
66
===================
77

88

9-
`easy_install` was released in 2004, as part of :ref:`setuptools`. It was
9+
:ref:`easy_install <easy_install>` was released in 2004, as part of :ref:`setuptools`. It was
1010
notable at the time for installing :term:`packages <Distribution Package>` from
1111
:term:`PyPI <Python Package Index (PyPI)>` using requirement specifiers, and
1212
automatically installing dependencies.
1313

14-
:ref:`pip` came later in 2008, as alternative to `easy_install`, although still
14+
:ref:`pip` came later in 2008, as alternative to :ref:`easy_install <easy_install>`, although still
1515
largely built on top of :ref:`setuptools` components. It was notable at the
1616
time for *not* installing packages as :term:`Eggs <Egg>` or from :term:`Eggs <Egg>` (but
1717
rather simply as 'flat' packages from :term:`sdists <Source Distribution (or
@@ -21,49 +21,49 @@ 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

6666
.. [1] https://setuptools.readthedocs.io/en/latest/easy_install.html#natural-script-launcher
6767
6868
69-
.. _pylauncher support: https://bitbucket.org/pypa/pylauncher
69+
.. _pylauncher support: https://bitbucket.org/vinay.sajip/pylauncher

0 commit comments

Comments
 (0)