Unverified Commit 37a0020e authored by Richard Si's avatar Richard Si Committed by GitHub
Browse files

Upgrade docs to Sphinx 3+ and add doc build test (#1613)

* Upgrade docs to Sphinx 3+
* Fix all the warnings...

- Fixed bad docstrings
- Fixed bad fenced code blocks in documentation
- Blocklisted some sections from being generated from the README
- Added missing documentation to index.rst
- Fixed an invalid autofunction directive in reference/reference_functions.rst
- Pin another documentation dependency

* Add documentation build test
parent e5bb92f5
Loading
Loading
Loading
Loading
+36 −0
Changes for .github/workflows/doc.yml: 36 added lines, 0 removed lines.
Original line number Diff line number Diff line
name: Documentation Build

on:
  push:
    paths:
      - "docs/**"
      - "README.md"
      - "CHANGES.md"
      - "CONTRIBUTING.md"
  pull_request:
    paths:
      - "docs/**"
      - "README.md"
      - "CHANGES.md"
      - "CONTRIBUTING.md"

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Set up Python 3.8
        uses: actions/setup-python@v2
        with:
          python-version: 3.8

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip setuptools wheel
          python -m pip install -e "."
          python -m pip install -r "docs/requirements.txt"

      - name: Build documentation
        run: sphinx-build -a -b html -W docs/ docs/_build/
+2 −2
Changes for README.md: 2 added lines, 2 removed lines.
Original line number Diff line number Diff line
@@ -464,7 +464,7 @@ Twisted and CPython:

Use the badge in your project's README.md:

```markdown
```md
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
```

@@ -625,7 +625,7 @@ Multiple contributions by:
- [Miroslav Shubernetskiy](mailto:miroslav@miki725.com)
- MomIsBestFriend
- [Nathan Goldbaum](mailto:ngoldbau@illinois.edu)
- [Nathan Hunt](mailtoneighthan.hunt@gmail.com)
- [Nathan Hunt](mailto:neighthan.hunt@gmail.com)
- [Neraste](mailto:neraste.herr10@gmail.com)
- [Nikolaus Waxweiler](mailto:madigens@gmail.com)
- [Ofek Lev](mailto:ofekmeister@gmail.com)
+3 −3
Changes for docs/black_primer.md: 3 added lines, 3 removed lines.
Original line number Diff line number Diff line
@@ -71,7 +71,7 @@ each parameter is explained below:
      "expect_formatting_changes": true,
      "git_clone_url": "https://github.com/cooperlees/aioexabgp.git",
      "long_checkout": false,
      "py_versions": ["all", "3.8"] // "all" ignores all other versions
      "py_versions": ["all", "3.8"]
    }
  }
}
@@ -103,9 +103,9 @@ Failed projects:
+++ tests/b303_b304.py	2020-05-17 20:06:42.753851 +0000
@@ -26,11 +26,11 @@
     maxint = 5  # this is okay
     # the following shouldn't crash
     # the following should not crash
     (a, b, c) = list(range(3))
     # it's different than this
     # it is different than this
     a, b, c = list(range(3))
-    a, b, c, = list(range(3))
+    a, b, c = list(range(3))
+1 −1
Changes for docs/compatible_configs.md: 1 added line, 1 removed line.
Original line number Diff line number Diff line
@@ -241,7 +241,7 @@ characters via `max-line-length = 88`.
<details>
<summary>pylintrc</summary>

```rc
```ini
[MESSAGES CONTROL]
disable = C0330, C0326

+26 −11
Changes for docs/conf.py: 26 added lines, 11 removed lines.
Original line number Diff line number Diff line
@@ -17,18 +17,15 @@
import string
from typing import Callable, List, Optional, Pattern, Tuple, Set
from dataclasses import dataclass
import os
import logging

from pkg_resources import get_distribution
from recommonmark.parser import CommonMarkParser

logging.basicConfig(format="%(levelname)s: %(message)s", level=logging.INFO)

LOG = logging.getLogger(__name__)

# Get a relative path so logs printing out SRC isn't too long.
CURRENT_DIR = Path(__file__).parent.relative_to(os.getcwd())
CURRENT_DIR = Path(__file__).parent
README = CURRENT_DIR / ".." / "README.md"
REFERENCE_DIR = CURRENT_DIR / "reference"
STATIC_DIR = CURRENT_DIR / "_static"
@@ -200,7 +197,7 @@ def process_sections(
# -- Project information -----------------------------------------------------

project = "Black"
copyright = "2018, Łukasz Langa and contributors to Black"
copyright = "2020, Łukasz Langa and contributors to Black"
author = "Łukasz Langa and contributors to Black"

# Autopopulate version
@@ -213,7 +210,6 @@ def process_sections(

custom_sections = [
    DocSection("the_black_code_style", CURRENT_DIR / "the_black_code_style.md",),
    DocSection("pragmatism", CURRENT_DIR / "the_black_code_style.md",),
    DocSection("editor_integration", CURRENT_DIR / "editor_integration.md"),
    DocSection("blackd", CURRENT_DIR / "blackd.md"),
    DocSection("black_primer", CURRENT_DIR / "black_primer.md"),
@@ -221,28 +217,47 @@ def process_sections(
    DocSection("change_log", CURRENT_DIR / ".." / "CHANGES.md"),
]

# Sphinx complains when there is a source file that isn't referenced in any of the docs.
# Since some sections autogenerated from the README are unused warnings will appear.
#
# Sections must be listed to what their name is when passed through make_filename().
blocklisted_sections_from_readme = {
    "license",
    "pragmatism",
    "testimonials",
    "used_by",
}

make_pypi_svg(release)
readme_sections = get_sections_from_readme()
readme_sections = [
    x for x in readme_sections if x.name not in blocklisted_sections_from_readme
]

process_sections(custom_sections, readme_sections)


# -- General configuration ---------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
needs_sphinx = "3.0"

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.napoleon"]
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.intersphinx",
    "sphinx.ext.napoleon",
    "recommonmark",
]

# If you need extensions of a certain version or higher, list them here.
needs_extensions = {"recommonmark": "0.5"}

# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

source_parsers = {".md": CommonMarkParser}

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
source_suffix = [".rst", ".md"]
Loading