Browse Source

Change documentation theme to Furo (#347)

* Add a ReadTheDocs.yml file

* Exclude .readthedocs.yml from distributions

* Switch documentation theme to Furo

* Drop "Copyright" from the __copyright__ variable

This is directly used for Sphinx documentation's copyright,
which expects only "date, names".

* Write a new intro in README and reuse it in docs

* Hide the TOCTree and add captions to them

* Fix links in packaging.tags documentation

* Remove the pygments style

* Fix RTD build

Co-authored-by: Pradyun Gedam <pradyunsg@users.noreply.github.com>
Co-authored-by: Brett Cannon <brcan@microsoft.com>
pull/353/head
Pradyun Gedam 2 years ago committed by GitHub
parent
commit
5d87153cc6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 15
      .readthedocs.yml
  2. 1
      MANIFEST.in
  3. 11
      README.rst
  4. 15
      docs/conf.py
  5. 15
      docs/index.rst
  6. 1
      docs/requirements.txt
  7. 7
      docs/tags.rst
  8. 2
      noxfile.py
  9. 2
      packaging/__about__.py

15
.readthedocs.yml

@ -0,0 +1,15 @@
version: 2
build:
image: latest
formats: [pdf]
sphinx:
configuration: docs/conf.py
python:
version: 3.8
install:
- requirements: docs/requirements.txt
- method: pip
path: .

1
MANIFEST.in

@ -10,6 +10,7 @@ recursive-include tests *.py
recursive-include tests hello-world-*
exclude noxfile.py
exclude .readthedocs.yml
exclude .travis.yml
exclude dev-requirements.txt
exclude tests/build-hello-world.sh

11
README.rst

@ -1,7 +1,16 @@
packaging
=========
Core utilities for Python packages.
.. start-intro
Reusable core utilities for various Python Packaging
`interoperability specifications <https://packaging.python.org/specifications/>`_.
This library provides utilities that implement the interoperability
specifications which have clearly one correct behaviour (eg: :pep:`440`)
or benefit greatly from having a single shared implementation (eg: :pep:`425`).
.. end-intro
The ``packaging`` project includes the following: version handling, specifiers,
markers, requirements, tags, utilities.

15
docs/conf.py

@ -7,11 +7,6 @@ from __future__ import absolute_import, division, print_function
import os
import sys
try:
import sphinx_rtd_theme
except ImportError:
sphinx_rtd_theme = None
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
@ -58,9 +53,6 @@ copyright = about["__copyright__"]
# directories to ignore when looking for source files.
exclude_patterns = ["_build"]
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx"
extlinks = {
"issue": ("https://github.com/pypa/packaging/issues/%s", "#"),
"pull": ("https://github.com/pypa/packaging/pull/%s", "PR #"),
@ -70,11 +62,8 @@ extlinks = {
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
if sphinx_rtd_theme:
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
else:
html_theme = "default"
html_theme = "furo"
html_title = "packaging"
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,

15
docs/index.rst

@ -1,7 +1,9 @@
Welcome to packaging
====================
Core utilities for Python packages
.. include:: ../README.rst
:start-after: start-intro
:end-before: end-intro
Installation
@ -14,11 +16,10 @@ You can install packaging with ``pip``:
$ pip install packaging
API
---
.. toctree::
:maxdepth: 1
:caption: API Documentation
:hidden:
version
specifiers
@ -27,12 +28,10 @@ API
tags
utils
Project
-------
.. toctree::
:maxdepth: 2
:caption: Project
:hidden:
development/index
security

1
docs/requirements.txt

@ -0,0 +1 @@
furo

7
docs/tags.rst

@ -215,7 +215,6 @@ to the implementation to provide.
platforms compatible with the current system.
:param bool warn: Whether warnings should be logged. Defaults to ``False``.
.. _abbreviation codes: https://www.python.org/dev/peps/pep-0425/#python-tag
.. _compressed tag set: https://www.python.org/dev/peps/pep-0425/#compressed-tag-sets
.. _platform compatibility tags: https://packaging.python.org/specifications/platform-compatibility-tags/
.. _PEP 425: https://www.python.org/dev/peps/pep-0425/
.. _`abbreviation codes`: https://www.python.org/dev/peps/pep-0425/#python-tag
.. _`compressed tag set`: https://www.python.org/dev/peps/pep-0425/#compressed-tag-sets
.. _`platform compatibility tags`: https://packaging.python.org/specifications/platform-compatibility-tags/

2
noxfile.py

@ -60,7 +60,7 @@ def lint(session):
@nox.session(python="3.9")
def docs(session):
shutil.rmtree("docs/_build", ignore_errors=True)
session.install("sphinx", "sphinx-rtd-theme")
session.install("furo")
variants = [
# (builder, dest)

2
packaging/__about__.py

@ -24,4 +24,4 @@ __author__ = "Donald Stufft and individual contributors"
__email__ = "donald@stufft.io"
__license__ = "BSD-2-Clause or Apache-2.0"
__copyright__ = "Copyright 2014-2019 %s" % __author__
__copyright__ = "2014-2019 %s" % __author__

Loading…
Cancel
Save