Merge pull request #175 from scipp/black

Swicth to Black python formatting and fix some docs issues

Author: nvaytet

.github/workflows/docs.yml

@@ -13,6 +13,11 @@ on:
         default: ''
         required: false
         type: string
+      branch:
+        description: 'Branch/tag with documentation source. If not set, the current branch will be used.'
+        default: ''
+        required: false
+        type: string
       platform:
         default: 'ubuntu-22.04'
         type: string
@@ -25,6 +30,11 @@ on:
         default: ''
         required: false
         type: string
+      branch:
+        description: 'Branch/tag with documentation source. If not set, the current branch will be used.'
+        default: ''
+        required: false
+        type: string
       platform:
         default: 'ubuntu-22.04'
         type: string
@@ -45,7 +55,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
         with:
-          ref: ${{ inputs.version }}
+          ref: ${{ inputs.branch == '' && github.ref_name || inputs.branch }}
           fetch-depth: 0  # history required so setuptools_scm can determine version
 
       - name: Setup conda environment
@@ -55,7 +65,7 @@ jobs:
           environment-file: environment.yml
           cache-env: true
 
-      - run: conda develop src
+      - run: python -m pip install .
       - run: jupyter --paths
       - run: python docs/make_docs.py --build-dir=html_${{ inputs.platform }}
 

.github/workflows/pr_and_main.yml

@@ -65,6 +65,8 @@ jobs:
     uses: ./.github/workflows/docs.yml
     with:
       publish: false
+      version: ${{ github.ref_name }}
+      branch: ${{ github.head_ref == '' && github.ref_name || github.head_ref }}
       platform: ${{ matrix.os }}
     strategy:
       fail-fast: false

.github/workflows/release.yml

@@ -100,8 +100,8 @@ jobs:
       - name: Set outputs
         id: version
         run: |
-          echo "new=$(python docs/version.py --repo=scipp --version=${GITHUB_REF_NAME} --action=is-new)" >> $GITHUB_OUTPUT
-          echo "replaced=$(python docs/version.py --repo=scipp --version=${GITHUB_REF_NAME} --action=get-replaced)" >> $GITHUB_OUTPUT
+          echo "new=$(python docs/version.py --version=${GITHUB_REF_NAME} --action=is-new)" >> $GITHUB_OUTPUT
+          echo "replaced=$(python docs/version.py --version=${GITHUB_REF_NAME} --action=get-replaced)" >> $GITHUB_OUTPUT
 
   replaced-docs:
     needs: [upload_packages, manage-versions]

.pre-commit-config.yaml

@@ -18,13 +18,10 @@ repos:
     hooks:
       - id: isort
         name: isort (python)
-  - repo: https://github.com/pre-commit/mirrors-yapf
-    rev: v0.32.0
+  - repo: https://github.com/psf/black
+    rev: 23.3.0
     hooks:
-      - id: yapf
-        args: [ "-i", "-r" ]
-        types: [ "python" ]
-        additional_dependencies: [ "toml" ]
+      - id: black
   - repo: https://github.com/kynan/nbstripout
     rev: 0.6.0
     hooks:

docs/conf.py

@@ -38,16 +38,19 @@ def add_buttons(
     base = "https://scipp.github.io"
     l1 = []
     l1.append({"type": "link", "text": "scipp", "url": f"{base}"})
+    l1.append({"type": "link", "text": "plopp", "url": f"{base}/plopp"})
     l1.append({"type": "link", "text": "scippnexus", "url": f"{base}/scippnexus"})
     l1.append({"type": "link", "text": "scippneutron", "url": f"{base}/scippneutron"})
     l1.append({"type": "link", "text": "ess", "url": f"{base}/ess"})
     header_buttons = context["header_buttons"]
-    header_buttons.append({
-        "type": "group",
-        "buttons": l1,
-        "icon": "fa fa-caret-down",
-        "text": "Related projects"
-    })
+    header_buttons.append(
+        {
+            "type": "group",
+            "buttons": l1,
+            "icon": "fa fa-caret-down",
+            "text": "Related projects",
+        }
+    )
     releases = version_info.minor_releases(first='0.1')
     if outdated:
         current = f"{long_version} (outdated)"
@@ -59,17 +62,12 @@ def add_buttons(
         entries = releases[1:]
     lines = [{"type": "link", "text": latest, "url": f"{base}/{project}"}]
     for r in entries:
-        lines.append({
-            "type": "link",
-            "text": f"{r}",
-            "url": f"{base}/{project}/release/{r}"
-        })
-    header_buttons.append({
-        "type": "group",
-        "buttons": lines,
-        "icon": "fa fa-caret-down",
-        "text": current
-    })
+        lines.append(
+            {"type": "link", "text": f"{r}", "url": f"{base}/{project}/release/{r}"}
+        )
+    header_buttons.append(
+        {"type": "group", "buttons": lines, "icon": "fa fa-caret-down", "text": current}
+    )
 
 
 sphinx_book_theme.add_launch_buttons = add_buttons
@@ -104,7 +102,7 @@ def add_buttons(
     'numpy': ('https://numpy.org/doc/stable/', None),
     'scipp': ('https://scipp.github.io/', None),
     'scipy': ('https://docs.scipy.org/doc/scipy/', None),
-    'xarray': ('https://xarray.pydata.org/en/stable/', None)
+    'xarray': ('https://xarray.pydata.org/en/stable/', None),
 }
 
 # autodocs includes everything, even irrelevant API internals. autosummary
@@ -198,7 +196,8 @@ def add_buttons(
         f"⚠️ You are viewing the documentation for an old version of {project}. "
         f"Switch to <a href='https://scipp.github.io/{project}' "
         "style='color:white;text-decoration:underline;'"
-        ">latest</a> version. ⚠️")
+        ">latest</a> version. ⚠️"
+    )
 
 html_logo = "_static/logo.svg"
 html_favicon = "_static/favicon.ico"
@@ -236,8 +235,15 @@ def add_buttons(
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'ess', u'ess Documentation', author, 'ess',
-     'One line description of project.', 'Miscellaneous'),
+    (
+        master_doc,
+        'ess',
+        u'ess Documentation',
+        author,
+        'ess',
+        'One line description of project.',
+        'Miscellaneous',
+    ),
 ]
 
 # -- Options for Matplotlib in notebooks ----------------------------------
@@ -255,9 +261,12 @@ def add_buttons(
 
 # Using normalize whitespace because many __str__ functions in scipp produce
 # extraneous empty lines and it would look strange to include them in the docs.
-doctest_default_flags = doctest.ELLIPSIS | doctest.IGNORE_EXCEPTION_DETAIL | \
-                        doctest.DONT_ACCEPT_TRUE_FOR_1 | \
-                        doctest.NORMALIZE_WHITESPACE
+doctest_default_flags = (
+    doctest.ELLIPSIS
+    | doctest.IGNORE_EXCEPTION_DETAIL
+    | doctest.DONT_ACCEPT_TRUE_FOR_1
+    | doctest.NORMALIZE_WHITESPACE
+)
 
 # -- Options for linkcheck ------------------------------------------------
 

docs/developer/style-guide.rst

@@ -73,7 +73,7 @@ Formatting
 
 Your Python code will be checked for errors and formatting when opening a PR.
 We use the `flake8 <https://flake8.pycqa.org/en/latest/>`_ linter to check code quality,
-and `yapf <https://github.com/google/yapf>`_ to enforce code formatting.
+and `black <https://github.com/psf/black>`_ to enforce code formatting.
 Make sure that running your code though these tools does not generate any output before
 you push your changes.
 
@@ -82,7 +82,7 @@ From the top level directory, you can use
 .. code-block:: sh
 
    >$ flake8 .
-   >$ yapf --diff --recursive .
+   >$ black .
 
 Jupyter notebooks style
 -----------------------