From 37a0020e073555ffe0921ec1356a27610aadcca4 Mon Sep 17 00:00:00 2001 From: Richard Si <63936253+ichard26@users.noreply.github.com> Date: Thu, 20 Aug 2020 18:06:41 -0400 Subject: [PATCH] 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 | 36 +++++++++++++++++++++++++ README.md | 4 +-- docs/black_primer.md | 6 ++--- docs/compatible_configs.md | 2 +- docs/conf.py | 37 ++++++++++++++++++-------- docs/index.rst | 3 ++- docs/reference/reference_functions.rst | 2 +- docs/requirements.txt | 5 ++-- src/black/__init__.py | 1 + 9 files changed, 75 insertions(+), 21 deletions(-) create mode 100644 .github/workflows/doc.yml diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml new file mode 100644 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 37b93c1..44f2d20 100644 --- 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 af41842..a2dd964 100644 --- 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 723fc88..25e959e 100644 --- a/docs/compatible_configs.md +++ b/docs/compatible_configs.md @@ -241,7 +241,7 @@ characters via `max-line-length = 88`.
pylintrc -```rc +```ini [MESSAGES CONTROL] disable = C0330, C0326 diff --git a/docs/conf.py b/docs/conf.py index 3343087..575a140 100644 --- 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 676644e..f03d247 100644 --- 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 b10eea9..1beecc1 100644 --- 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 a36fd8a..4cad9bc 100644 --- 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 2613b2f..d251136 100644 --- 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", -- 2.39.5