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:
 
 
 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)
 ```
 
 [![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)
 - [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)
 - [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,
       "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
 +++ 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))
      (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))
      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>
 
 <details>
 <summary>pylintrc</summary>
 

-```rc
+```ini

 [MESSAGES CONTROL]
 disable = C0330, C0326
 
 [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 string
 from typing import Callable, List, Optional, Pattern, Tuple, Set
 from dataclasses import dataclass

-import os

 import logging
 
 from pkg_resources import get_distribution
 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__)
 
 
 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"
 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"
 # -- 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
 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",),
 
 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"),
     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"),
 ]
 
     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()
 
 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.
 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.
 
 # 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"]
 
 
 # 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"]
 # 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
    installation_and_usage
    the_black_code_style
    pyproject_toml

+   compatible_configs

    editor_integration
    blackd
    black_primer
    version_control_integration
    editor_integration
    blackd
    black_primer
    version_control_integration

+   github_actions

    ignoring_unmodified_files
    contributing_to_black
    show_your_style
    ignoring_unmodified_files
    contributing_to_black
    show_your_style


@@ -66,5 +68,4 @@ Indices and tables
 ==================
 
 * :ref:`genindex`
 ==================
 
 * :ref:`genindex`

-* :ref:`modindex`

 * :ref:`search`
 * :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.standalone_comment_split
 

-.. autofunction:: black.split_line
+.. autofunction:: black.transform_line

 
 Caching
 -------
 
 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:
         ...
 
     A more complex example:

+

     >>> print(
     ...   black.format_str(
     ...     "def f(arg:str='')->None: hey",
     >>> print(
     ...   black.format_str(
     ...     "def f(arg:str='')->None: hey",