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

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
new file mode 100644 (file)
index 0000000..6023a02
--- /dev/null
+++ b/.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/

diff --git a/README.md b/README.md
index 37b93c143a207974fa2f6484b1e8b422e9a9594f..44f2d207c8b1bca4581384a20049693786fb2fa9 100644 (file)
--- a/README.md
+++ b/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)

diff --git a/docs/black_primer.md b/docs/black_primer.md
index af4184233e28d05073be6177777554dbeb9cf493..a2dd964b7dc53d485292eccb2d8248235d858b32 100644 (file)
--- a/docs/black_primer.md
+++ b/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))

diff --git a/docs/compatible_configs.md b/docs/compatible_configs.md
index 723fc889c00c36ec29ba59afaed690c60f82dccb..25e959e328110a12b7dc90df022b4bc9b1444a1e 100644 (file)
--- a/docs/compatible_configs.md
+++ b/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
 

diff --git a/docs/conf.py b/docs/conf.py
index 3343087cfbd02b7b9fe89dbb4412ce590096c1ae..575a14011e4bbc2917de9bdc6757cb89baec144b 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -17,18 +17,15 @@ import re
 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 @@ for sp in "abcfr":
 
 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 @@ custom_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"]

diff --git a/docs/index.rst b/docs/index.rst
index 676644ec6c6b5bcde9d0477d806da2e9641a2717..f03d247d949a6313adb6d0dfcd50d43d1064807d 100644 (file)
--- a/docs/index.rst
+++ b/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`

diff --git a/docs/reference/reference_functions.rst b/docs/reference/reference_functions.rst
index b10eea9b01f47ab4f1daff9774ce0ba4826a17a1..1beecc1032550cc4e122aff1e22db6bf3ed02d38 100644 (file)
--- a/docs/reference/reference_functions.rst
+++ b/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
 -------

diff --git a/docs/requirements.txt b/docs/requirements.txt
index a36fd8a675b2307fa0ac9920b75799be6e3c441e..4cad9bc205b626c757ffc1fff1fd0fae23ab9f37 100644 (file)
--- a/docs/requirements.txt
+++ b/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
\ No newline at end of file

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 2613b2f9e16c7b9ef2582d1164ca123593786d69..d251136942a37a86c8304c341408167ea4dc3f10 100644 (file)
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -952,6 +952,7 @@ def format_str(src_contents: str, *, mode: Mode) -> FileContent:
         ...
 
     A more complex example:
+
     >>> print(
     ...   black.format_str(
     ...     "def f(arg:str='')->None: hey",