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

.github/workflows/doc.yml

@@ -0,0 +1,36 @@
+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/

README.md

@@ -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)

docs/black_primer.md

@@ -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))

docs/compatible_configs.md

@@ -241,7 +241,7 @@ characters via `max-line-length = 88`.
 <details>
 <summary>pylintrc</summary>
 
-```rc
+```ini
 [MESSAGES CONTROL]
 disable = C0330, C0326
 

docs/conf.py

@@ -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"]

docs/index.rst

@@ -51,10 +51,12 @@ Contents
    installation_and_usage
    the_black_code_style
    pyproject_toml
+   compatible_configs
    editor_integration
    blackd
    black_primer
    version_control_integration
+   github_actions
    ignoring_unmodified_files
    contributing_to_black
    show_your_style
@@ -66,5 +68,4 @@ Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`

docs/reference/reference_functions.rst

@@ -89,7 +89,7 @@ Split functions
 
 .. autofunction:: black.standalone_comment_split
 
-.. autofunction:: black.split_line
+.. autofunction:: black.transform_line
 
 Caching
 -------

docs/requirements.txt

@@ -1,2 +1,3 @@
-recommonmark==0.4.0
-Sphinx==1.7.2
+recommonmark==0.6.0
+Sphinx==3.2.1
+Pygments==2.6.1

src/black/__init__.py

@@ -952,6 +952,7 @@ def f(arg: str = "") -> None:
         ...
 
     A more complex example:
+
     >>> print(
     ...   black.format_str(
     ...     "def f(arg:str='')->None: hey",