Update docs (Closes #110) (#111)

.github/workflows/continuous-integration-workflow.yml

@@ -5,19 +5,16 @@ concurrency:
   group: ${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
-
 on:
   push:
     branches:
-    - master
+      - master
   pull_request:
     branches:
-    - '*'
+      - "*"
 
 jobs:
-
   run-tests:
-
     name: Run tests for ${{ matrix.os }} on ${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}
     env:
@@ -26,8 +23,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
-        python-version: ['3.8', '3.9', '3.10']
+        os: ["ubuntu-latest", "macos-latest", "windows-latest"]
+        python-version: ["3.9", "3.10", "3.11"]
 
     steps:
       - uses: actions/checkout@v2
@@ -37,6 +34,8 @@ jobs:
       - uses: conda-incubator/setup-miniconda@v2
         with:
           auto-update-conda: true
+          channels: conda-forge,defaults
+          channel-priority: true
           python-version: ${{ matrix.python-version }}
 
       - name: Install core dependencies.
@@ -48,33 +47,29 @@ jobs:
         run: tox -e pytest -- tests -m end_to_end --cov=./ --cov-report=xml -n auto
 
       - name: Upload coverage reports of end-to-end tests.
-        if: runner.os == 'Linux' && matrix.python-version == '3.9'
+        if: runner.os == 'Linux' && matrix.python-version == '3.11'
         shell: bash -l {0}
         run: bash <(curl -s https://codecov.io/bash) -F end_to_end -c
 
-
   pre-commit:
-
     name: Run pre-commit.
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v2
 
-      - name: Set up Python 3.9
+      - name: Set up Python 3.11
         uses: actions/setup-python@v1
         with:
-          python-version: 3.9
+          python-version: 3.11
 
       - name: Install dependencies
         run: pip install tox
 
       - name: Run pre-commit
         run: tox -e pre-commit
 
-
   docs:
-
     name: Run documentation.
     runs-on: ubuntu-latest
 
@@ -83,6 +78,7 @@ jobs:
       - uses: conda-incubator/setup-miniconda@v2
         with:
           auto-update-conda: true
+          python-version: 3.9
 
       - name: Install core dependencies.
         shell: bash -l {0}

.gitignore

@@ -1,3 +1,4 @@
+docs/scripts/latex/*.png
 *-blx.bib
 *.asv
 *.aux

.pre-commit-config.yaml

@@ -1,63 +1,124 @@
-# Exclude every file or folder starting with a dot.
-exclude: ^(\.|\{\{cookiecutter\.project_slug\}\}/.+)
+exclude: ^(\.|{{cookiecutter\.project_slug}}/.+)
+
 repos:
-  - repo: https://github.com/asottile/reorder_python_imports
-    rev: v3.8.5
-    hooks:
-      - id: reorder-python-imports
-        args: [--unclassifiable-application-module=src]
-  - repo: https://github.com/pre-commit/pre-commit-hooks
+-   repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.3.0
     hooks:
-      - id: check-yaml
-      - id: check-added-large-files
-        args: ["--maxkb=100000"] # Set to max file size in Github
-      - id: check-byte-order-marker
-        types: [text]
-      - id: check-merge-conflict
-      - id: check-json
-      - id: pretty-format-json
-        args: [--autofix, --no-sort-keys, --no-ensure-ascii]
-      - id: trailing-whitespace
-  - repo: https://github.com/asottile/pyupgrade
-    rev: v3.1.0
-    hooks:
-      - id: pyupgrade
+    -   id: check-added-large-files
+        args: ['--maxkb=25']
+    -   id: check-case-conflict
+    -   id: check-merge-conflict
+    -   id: check-vcs-permalinks
+    -   id: check-yaml
+        exclude:  |
+            (?x)^(
+                {{cookiecutter.project_slug}}/environment.yml|
+                {{cookiecutter.project_slug}}/.pre-commit-config.yaml
+            )$
+    -   id: debug-statements
+    -   id: end-of-file-fixer
+    -   id: fix-byte-order-marker
+    -   id: mixed-line-ending
+    -   id: no-commit-to-branch
+        args: [--branch, main]
+    -   id: trailing-whitespace
+-   repo: https://github.com/pre-commit/pygrep-hooks
+    rev: v1.9.0
+    hooks:
+    -   id: python-check-blanket-noqa
+    -   id: python-check-mock-methods
+    -   id: python-no-eval
+    -   id: python-no-log-warn
+    -   id: python-use-type-annotations
+    -   id: text-unicode-replacement-char
+-   repo: https://github.com/asottile/pyupgrade
+    rev: v2.37.1
+    hooks:
+    -   id: pyupgrade
         args: [--py37-plus]
-  - repo: https://github.com/asottile/blacken-docs
-    rev: v1.12.1
-    hooks:
-      - id: blacken-docs
-        additional_dependencies: [black]
-        files: '(\.md|\.rst)$'
-  - repo: https://github.com/psf/black
-    rev: 22.10.0
-    hooks:
-      - id: black
-        language_version: python3.9
-  - repo: https://github.com/PyCQA/flake8
-    rev: 5.0.4
-    hooks:
-      - id: flake8
-        exclude: docs/bld/example/r/r_example/src/documentation/conf.py
-        additional_dependencies:
-          [
+-   repo: https://github.com/asottile/reorder_python_imports
+    rev: v3.8.1
+    hooks:
+    -   id: reorder-python-imports
+-   repo: https://github.com/psf/black
+    rev: 22.6.0
+    hooks:
+    -   id: black
+-   repo: https://github.com/myint/docformatter
+    rev: v1.3.1
+    hooks:
+    -   id: docformatter
+        args: [--in-place, --wrap-summaries, "88", --wrap-descriptions, "88", --blank]
+-   repo: https://github.com/PyCQA/flake8
+    rev: 4.0.1
+    hooks:
+    -   id: flake8
+        additional_dependencies: [
+            flake8-alfred,
             flake8-bugbear,
             flake8-builtins,
             flake8-comprehensions,
-            flake8-deprecated,
             flake8-docstrings,
             flake8-eradicate,
             flake8-print,
-            flake8-rst-docstrings,
+            flake8-pytest-style,
             flake8-todo,
+            flake8-typing-imports,
+            flake8-unused-arguments,
             pep8-naming,
             pydocstyle,
-          ]
-        # Harmonizing flake8 and black
-        args:
-          [
-            "--max-line-length=88",
-            "--ignore=E203,E402,E501,E800,W503",
-            "--select=B,C,E,F,W,T4,B9",
-          ]
+            Pygments,
+        ]
+        args: [--exclude, "conf.py, docs/"]
+-   repo: https://github.com/econchick/interrogate
+    rev: 1.5.0
+    hooks:
+    -   id: interrogate
+        args: [
+            -v,
+            --fail-under=40,
+            --config,
+            pyproject.toml,
+            --exclude,
+            "{{cookiecutter.project_slug}}/"
+        ]
+        pass_filenames: false
+-   repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.14
+    hooks:
+    -   id: mdformat
+        additional_dependencies: [
+            mdformat-gfm,
+            mdformat-black,
+        ]
+        args: [--wrap, "88"]
+        files: (README\.md)
+-   repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.14
+    hooks:
+    -   id: mdformat
+        additional_dependencies: [
+            mdformat-myst,
+            mdformat-black,
+        ]
+        args: [--wrap, "88"]
+        files: (docs/.)
+        # Exclude files with admonitions.
+        # exclude: |
+        #     (?x)^(
+        #         path/to/file.py
+        #     )$
+-   repo: https://github.com/codespell-project/codespell
+    rev: v2.1.0
+    hooks:
+    -   id: codespell
+-   repo: https://github.com/guilatrova/tryceratops
+    rev: v1.1.0
+    hooks:
+    -   id: tryceratops
+        exclude: "{{cookiecutter.project_slug}}/pyproject.toml"
+-   repo: meta
+    hooks:
+    -   id: check-hooks-apply
+    -   id: check-useless-excludes
+    # -   id: identity  # Prints all files passed to pre-commits. Debugging.

cookiecutter.json

@@ -9,7 +9,8 @@
   "github_email": "{{ cookiecutter.email }}",
   "git_remote_url": "",
   "version": "0.0.1",
-  "python_version": "3.8",
+  "python_version": "3.11",
+  "is_ci": ["no", "yes"],
   "add_tox": [
     "yes",
     "no"
@@ -22,10 +23,6 @@
     "yes",
     "no"
   ],
-  "add_readthedocs": [
-    "yes",
-    "no"
-  ],
   "add_codecov": [
     "yes",
     "no"

docs/Makefile

@@ -1,5 +1,5 @@
 # Minimal makefile for Sphinx documentation
-#
+
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.

docs/rtd_environment.yml

@@ -3,7 +3,7 @@ channels:
   - nodefaults
 
 dependencies:
-  - python=3.9
+  - python==3.9
   - pip
   - setuptools_scm
   - toml

docs/scripts/task_create_visualization.py

@@ -7,10 +7,10 @@
 import pytask
 
 SRC = Path(__file__).parent.resolve()  # root/docs/scripts
-FIGURES = SRC.parent.resolve().joinpath("source").joinpath("figures").resolve()
+FIGURES = SRC.parent.joinpath("source", "figures", "generated").resolve()
 sys.path.append(str(SRC))
 
-from visualization_functions import visualize_organisational_steps
+from visualization_functions import visualize_organisational_steps  # noqa: E402
 
 
 for case in ["model_steps_full", "model_steps_select", "steps_only_full"]:
@@ -28,16 +28,20 @@ def task_visualize_organisational_steps(produces, case):
 
 for tex_file in ["root_bld_src", "src"]:
 
-    @pytask.mark.depends_on(SRC.joinpath("latex").joinpath(f"{tex_file}.tex"))
-    @pytask.mark.produces(SRC.joinpath(f"{tex_file}.png"))
+    @pytask.mark.depends_on(SRC.joinpath("latex", f"{tex_file}.tex"))
+    @pytask.mark.produces(SRC.joinpath("latex", f"{tex_file}.png"))
     @pytask.mark.task(id=tex_file)
     def task_compile_latex(depends_on):
-        subprocess.Popen(["pdflatex", "--shell-escape", str(depends_on)])
+        subprocess.run(
+            ("pdflatex", "--shell-escape", depends_on.name), cwd=depends_on.parent
+        )
         time.sleep(1)
-        subprocess.Popen(["pdflatex", "--shell-escape", str(depends_on)])
+        subprocess.run(
+            ("pdflatex", "--shell-escape", depends_on.name), cwd=depends_on.parent
+        )
         time.sleep(1)
 
-    @pytask.mark.depends_on(SRC.joinpath(f"{tex_file}.png"))
+    @pytask.mark.depends_on(SRC.joinpath("latex", f"{tex_file}.png"))
     @pytask.mark.produces(FIGURES.joinpath(f"{tex_file}.png"))
     @pytask.mark.task(id=tex_file)
     def task_copy_png_to_figures(depends_on, produces):

docs/scripts/visualization_functions.py

@@ -14,7 +14,7 @@ def visualize_organisational_steps(case):
     """
     fig = go.Figure()
 
-    # define coordinate dimenions
+    # define coordinate dimensions
     fig.add_trace(
         go.Scatter(
             x=[0.75, 4.3],
@@ -85,6 +85,7 @@ def update_fig_with_shape(case, fig):
                 )
     else:
         raise ValueError(
-            "Case must be in {'steps_only_full', 'model_steps_full', 'model_steps_select'}"
+            "Case must be in {'steps_only_full', 'model_steps_full', "
+            "'model_steps_select'}"
         )
     return fig

docs/source/example_project/dag.rst → docs/source/background/dag.rst

@@ -34,4 +34,4 @@ different specifications. As a case in point, consider the DAG for an early vers
 
 Do you want to keep those dependencies in your head? Or would it be useful to
 specify them once and for all in order to have more time for thinking about
-research? The next section shows you how to do that.
+research? The next section shows you how to do that.

docs/source/example_project/design_rationale.rst → docs/source/background/design_rationale.rst

@@ -6,15 +6,7 @@ The design of the project templates is guided by the following main thoughts:
 #. **Re-use of code and data instead of copying and pasting:** Else you will forget the
    copy & paste step at some point down the road. At best, this leads to errors; at
    worst, to misinterpreting the results.
-
-   ..
-     comment:: What is the difference between re-use code and copy-paste?
-
 #. **Be as language-agnostic as possible:** Make it easy to use the best tool for a
    particular task and to mix tools in a project.
 #. **Separation of inputs and outputs:** Required to find your way around in a complex
    project.
-
-I will not touch upon the last point until the section on how to organise the workflow
-below. The remainder of this page introduces an example and a general concept of how to
-think about the first four points.