Merge pull request #579 from dmgav/black-and-isort

Apply Black and ISort, rearrange the documentation sources

.flake8

@@ -2,10 +2,11 @@
 exclude =
     .git,
     __pycache__,
-    build,
-    dist,
+    build/*,
+    dist/*,
     versioneer.py,
     pyxrf/_version.py,
-    docs/conf.py,
-    docs/sphinxext/*
+    docs/*
+# There are some errors produced by 'black', therefore unavoidable
+ignore = E203, W503
 max-line-length = 115

.github/CONTRIBUTING.md

@@ -38,10 +38,10 @@ characters.  If the commit is related to a ticket, indicate that with
 "See #3456", "See ticket 3456", "Closes #3456" or similar.
 ```
 
-Describing the motivation for a change, the nature of a bug for bug fixes 
-or some details on what an enhancement does are also good to include in a 
-commit message. Messages should be understandable without looking at the code 
-changes. 
+Describing the motivation for a change, the nature of a bug for bug fixes
+or some details on what an enhancement does are also good to include in a
+commit message. Messages should be understandable without looking at the code
+changes.
 
 Standard acronyms to start the commit message with are:
 ```
@@ -64,7 +64,7 @@ REL: related to releases
 * Now push to your fork
 * Submit a [pull request](https://help.github.com/articles/using-pull-requests) to this branch. This is a start to the conversation.
 
-At this point you're waiting on us. We like to at least comment on pull requests within three business days 
+At this point you're waiting on us. We like to at least comment on pull requests within three business days
 (and, typically, one business day). We may suggest some changes or improvements or alternatives.
 
 Hints to make the integration of your changes easy (and happen faster):

.github/workflows/black.yml_ → .github/workflows/black.yml

@@ -6,8 +6,8 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
       - name: Install Dependencies
         run: |
           # These packages are installed in the base environment but may be older
@@ -18,4 +18,4 @@ jobs:
           pip install black
       - name: Run black
         run: |
-          black . --check
+          black . --check

.github/workflows/docs.yml

@@ -12,9 +12,9 @@ jobs:
       fail-fast: false
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
@@ -29,7 +29,7 @@ jobs:
         python -m pip install --upgrade pip setuptools numpy
 
         pip install -r requirements-dev.txt
-        pip install -r requirements-doc.txt
+        pip install -r requirements-docs.txt
         pip install .
 
         # # python setup.py install build_ext -i
@@ -39,10 +39,20 @@ jobs:
         pip list
     - name: Build Docs
       run: |
-        pip install -r requirements-doc.txt
         pushd ../
         git clone https://github.com/scikit-beam/scikit-beam-examples.git
         popd
         pushd docs
         bash build_docs.sh
         popd
+    - name: Deploy documentation to nsls-ii.github.io
+      if: github.repository_owner == 'scikit-beam' && github.ref_name == 'master'
+      # We pin to the SHA, not the tag, for security reasons.
+      # https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
+      uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501  # v3.7.3
+      with:
+        deploy_key: ${{ secrets.GITHUB_TOKEN }}
+        publish_branch: master
+        publish_dir: ./docs/build/html
+        keep_files: true  # Keep old files.
+        force_orphan: false  # Keep git history.

.github/workflows/flake8.yml

@@ -6,8 +6,8 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
       - name: Install Dependencies
         run: |
           # These packages are installed in the base environment but may be older
@@ -18,4 +18,4 @@ jobs:
           pip install flake8
       - name: Run flake8
         run: |
-          flake8
+          flake8

.github/workflows/isort.yml_ → .github/workflows/isort.yml

@@ -6,8 +6,8 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
       - name: Install Dependencies
         run: |
           # These packages are installed in the base environment but may be older
@@ -18,4 +18,4 @@ jobs:
           pip install isort
       - name: Run ISort
         run: |
-          isort . -c
+          isort . -c

.github/workflows/pre-commit.yml

@@ -0,0 +1,33 @@
+name: pre-commit
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  lint:
+    # pull requests are a duplicate of a branch push if within the same repo.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository
+
+    name: Check code style
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-python@v4
+
+      - name: Install dev dependencies
+        run: |
+          set -vxeuo pipefail
+          pip install -r requirements-dev.txt
+          python -m pip list
+
+      - name: Run pre-commit
+        run: pre-commit run --all-files

.github/workflows/python-publish.yml_

@@ -15,9 +15,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Python
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v4
       with:
         python-version: '3.x'
     - name: Install dependencies

.github/workflows/testing.yml

@@ -37,10 +37,10 @@ jobs:
         shell: bash -l {0}
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v4
       with:
         # This step is not expected to influence the test, since the test is run in Conda environment
         python-version: "3.10"

.gitignore

@@ -54,8 +54,8 @@ coverage.xml
 *.log
 
 # Sphinx documentation
-docs/_build/
-docs/resource/api/core/_as_gen/
+docs/build/
+docs/source/generated/
 
 # pytest
 .pytest_cache/

.isort.cfg

@@ -2,4 +2,4 @@
 line_length = 115
 multi_line_output = 3
 include_trailing_comma = True
-profile = black
+profile = black

.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+default_language_version:
+    python: python3
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: https://github.com/ambv/black
+    rev: 23.3.0
+    hooks:
+      - id: black
+  - repo: https://github.com/pycqa/flake8
+    rev: 6.0.0
+    hooks:
+      - id: flake8
+  - repo: https://github.com/pycqa/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.6.1
+    hooks:
+      - id: nbstripout

AUTHORS.rst

@@ -0,0 +1,13 @@
+=======
+Credits
+=======
+
+Maintainer
+----------
+
+* Brookhaven National Laboratory <>
+
+Contributors
+------------
+
+None yet. Why not be the first? See: CONTRIBUTING.rst