diff --git a/.editorconfig b/.editorconfig index 8b15eaa..3146498 100644 --- a/.editorconfig +++ b/.editorconfig @@ -9,3 +9,6 @@ trim_trailing_whitespace = true [*.{ipynb,md}] indent_size = unset + +[*.{py,toml}] +indent_size = 4 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..4f243e6 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,30 @@ +name: CI + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +on: + push: + branches: + - main + - epic/* + - "[0-9]+.[0-9]+.x" + pull_request: + branches: + - main + - epic/* + - "[0-9]+.[0-9]+.x" + workflow_dispatch: + inputs: + specific-pip-packages: + description: Run CI with specific pip packages + required: false + type: string + +jobs: + style: + if: inputs.specific-pip-packages == '' + secrets: + token: ${{ secrets.PAT }} + uses: ComPWA/actions/.github/workflows/pre-commit.yml@v1 diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e13fef8..d964372 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -17,7 +17,7 @@ jobs: - uses: actions/setup-python@v4 with: python-version: "3.10" - - run: pip install -r requirements.txt + - run: pip install -e .[doc] tox - name: Fetch Jupyter cache uses: actions/cache@v3 with: @@ -36,7 +36,7 @@ jobs: data path: | ./docs/data - - run: jupyter book build docs/ -W + - run: tox -e docnb - uses: actions/upload-pages-artifact@v2 if: always() with: diff --git a/.gitignore b/.gitignore index f8d36ff..1bf9f1a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,44 @@ +# Output files *.csv *.dat *.txt +data/ + +# Build files +*.egg-info/ +*build/ +.eggs/ +.fuse_* +dist/ +version.py + +# Temporary files +*.pyc +*condaenv.* +.coverage +.coverage.* .ipynb_checkpoints/ +.mypy*/ .pytest_cache/ .virtual_documents/ +__pycache__/ _build/ -data/ -docs/lecture18 +htmlcov/ +jupyter_execute/ +prof/ + +# Virtual environments +*venv/ +.tox/ +pyvenv*/ + +# Settings +.idea/ +**.code-workspace + +# Exceptions +!.github/*.yml +!.github/*/*.yml +!.pre-commit-config.yaml +!.vscode/*.json +!environment.yml diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 36cd30c..fb993b6 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,6 +1,8 @@ ci: autoupdate_commit_msg: "MAINT: update pre-commit config file" autoupdate_schedule: quarterly + skip: + - taplo repos: - repo: meta @@ -13,6 +15,7 @@ repos: hooks: - id: check-case-conflict - id: check-json + - id: check-toml - id: check-yaml - id: end-of-file-fixer - id: mixed-line-ending @@ -84,3 +87,15 @@ repos: rev: v3.0.3 hooks: - id: prettier + + - repo: https://github.com/ComPWA/mirrors-taplo + rev: v0.8.1 + hooks: + - id: taplo + + - repo: https://github.com/pappasam/toml-sort + rev: v0.23.1 + hooks: + - id: toml-sort + args: + - --in-place diff --git a/.taplo.toml b/.taplo.toml new file mode 100644 index 0000000..0db1df7 --- /dev/null +++ b/.taplo.toml @@ -0,0 +1,12 @@ +[formatting] +align_comments = false +align_entries = false +allowed_blank_lines = 1 +array_auto_collapse = false +array_auto_expand = true +array_trailing_comma = true +column_width = 88 +compact_inline_tables = true +indent_string = " " +reorder_arrays = true +reorder_keys = true diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 8c7aa0c..73f61b5 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -8,16 +8,20 @@ "github.vscode-github-actions", "github.vscode-pull-request-github", "mhutchie.git-graph", + "ms-python.black-formatter", + "ms-python.isort", "ms-python.python", "ms-toolsai.jupyter", "ms-toolsai.vscode-jupyter-cell-tags", "ms-toolsai.vscode-jupyter-slideshow", "ms-vscode.live-server", "stkb.rewrap", + "tamasfe.even-better-toml", "tyriar.sort-lines", "yzhang.markdown-all-in-one" ], "unwantedRecommendations": [ + "bungcip.better-toml", "davidanson.vscode-markdownlint", "ms-python.mypy-type-checker", "travisillig.vscode-json-stable-stringify" diff --git a/.vscode/settings.json b/.vscode/settings.json index c293661..86d5f07 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -3,7 +3,29 @@ "editor.rulers": [72], "rewrap.wrappingColumn": 72 }, + "[json]": { + "editor.defaultFormatter": "esbenp.prettier-vscode" + }, + "[jsonc]": { + "editor.defaultFormatter": "esbenp.prettier-vscode" + }, + "[markdown]": { + "editor.defaultFormatter": "esbenp.prettier-vscode" + }, + "[python]": { + "editor.codeActionsOnSave": { + "source.organizeImports": true + }, + "editor.defaultFormatter": "ms-python.black-formatter", + "editor.rulers": [88] + }, + "[yaml]": { + "editor.defaultFormatter": "esbenp.prettier-vscode" + }, + "black-formatter.importStrategy": "useBundled", "editor.formatOnSave": true, + "github-actions.workflows.pinned.workflows": [".github/workflows/ci.yml"], + "isort.args": ["--profile", "black"], "livePreview.defaultPreviewPath": "docs/_build/html", "notebook.gotoSymbols.showAllSymbols": true, "rewrap.wrappingColumn": 88 diff --git a/README.md b/README.md index e9ca859..047afba 100644 --- a/README.md +++ b/README.md @@ -25,10 +25,20 @@ This (unofficial) repository contains the exercises for the [STRONG2020 HaSP Sch ## Documentation -The website [compwa.github.io/strong2020-salamanca](https://compwa.github.io/strong2020-salamanca) is automatically generated from the notebooks in this repository using [Jupyter Book](https://jupyterbook.org). You can also run the notebooks and build the documentation locally as follows: +The website [compwa.github.io/strong2020-salamanca](https://compwa.github.io/strong2020-salamanca) is automatically generated from the notebooks in this repository using [Sphinx](https://www.sphinx-doc.org) and [MyST-NB](https://myst-nb.rtfd.io). You can also run the notebooks and build the documentation locally as follows: ```shell -jb build docs/ +tox -e docnb ``` -Adding the flag `-W` renders warnings as errors, which is useful for checking whether the notebooks run correctly. +Alternatively, you can run the notebooks without building the documentation with + +```shell +tox -e nb +``` + +or build the documentation without running the notebooks with + +```shell +tox -e doc +``` diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..0f348f3 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +lecture18 diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index e6598e6..0000000 --- a/docs/_config.yml +++ /dev/null @@ -1,40 +0,0 @@ -title: Solutions to STRON2020 HaSP School -author: Participants of the STRONG2020 HaSP School -copyright: "2023" -logo: https://indico.ific.uv.es/event/6803/logo-2761386249.png - -exclude_patterns: - - .virtual_documents/* - - lecture24_utilities.ipynb - -execute: - allow_errors: false - execute_notebooks: cache - timeout: 600 - -html: - use_issues_button: true - use_repository_button: true - -launch_buttons: - binderhub_url: https://mybinder.org - colab_url: https://colab.research.google.com - notebook_interface: jupyterlab - -only_build_toc_files: true - -repository: - url: https://github.com/ComPWA/strong2020-salamanca - path_to_book: docs - branch: main - -sphinx: - config: - html_js_files: - - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js - mathjax_path: https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js - nb_execution_show_tb: True - suppress_warnings: - - mystnb.unknown_mime_type - extra_extensions: - - sphinx_exercise diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 0000000..02a31fd Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/_static/logo.svg b/docs/_static/logo.svg new file mode 100755 index 0000000..ab38838 --- /dev/null +++ b/docs/_static/logo.svg @@ -0,0 +1,89 @@ + + + + + + + + + + + + + + + + + + + diff --git a/docs/_toc.yml b/docs/_toc.yml index 24ec4db..bb8f5a9 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -1,4 +1,3 @@ -format: jb-book root: index -chapters: +entries: - glob: lecture* diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..442852c --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,113 @@ +import os + + +def get_execution_mode() -> str: + if "FORCE_EXECUTE_NB" in os.environ: + print("\033[93;1mWill run ALL Jupyter notebooks!\033[0m") + return "force" + if "EXECUTE_NB" in os.environ: + return "cache" + return "off" + + +REPO_NAME = "strong2020-salamanca" +BRANCH = "main" + +author = "Participants of the STRONG2020 HaSP School" +autosectionlabel_prefix_document = True +comments_config = { + "hypothesis": True, +} +copybutton_prompt_is_regexp = True +copybutton_prompt_text = r">>> |\.\.\. " # doctest +copyright = "2023" +exclude_patterns = [ + "_build", + "lecture24_utilities.ipynb", +] +extensions = [ + "myst_nb", + "sphinx_book_theme", + "sphinx_comments", + "sphinx_copybutton", + "sphinx_design", + "sphinx_exercise", + "sphinx_external_toc", + "sphinx_togglebutton", +] +external_toc_exclude_missing = True +external_toc_path = "_toc.yml" +html_favicon = "_static/favicon.ico" +html_js_files = [ + "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js" +] +html_last_updated_fmt = "%-d %B %Y" +html_logo = "_static/logo.svg" +html_show_copyright = False +html_static_path = ["_static"] +html_theme = "sphinx_book_theme" +html_theme_options = { + "icon_links": [ + { + "name": "GitHub", + "url": f"https://github.com/ComPWA/{REPO_NAME}", + "icon": "fa-brands fa-github", + }, + { + "name": "Indico", + "url": "https://indico.ific.uv.es/event/6803", + "icon": "https://indico.cern.ch/images/indico.ico", + "type": "url", + }, + { + "name": "Launch on Binder", + "url": ( + f"https://mybinder.org/v2/gh/ComPWA/{REPO_NAME}/{BRANCH}?filepath=docs" + ), + "icon": "https://mybinder.readthedocs.io/en/latest/_static/favicon.png", + "type": "url", + }, + { + "name": "Launch on Colaboratory", + "url": f"https://colab.research.google.com/github/ComPWA/{REPO_NAME}/blob/{BRANCH}", + "icon": "https://avatars.githubusercontent.com/u/33467679?s=100", + "type": "url", + }, + { + "name": "Common Partial Wave Analysis", + "url": "https://compwa-org.rtfd.io", + "icon": "https://compwa-org.readthedocs.io/_static/favicon.ico", + "type": "url", + }, + ], + "launch_buttons": { + "binderhub_url": "https://mybinder.org", + "colab_url": "https://colab.research.google.com", + "notebook_interface": "jupyterlab", + }, + "path_to_docs": "docs", + "repository_branch": "main", + "repository_url": "https://github.com/ComPWA/strong2020-salamanca", + "use_issues_button": True, +} +html_title = "Solutions to STRON2020 HaSP School" +linkcheck_anchors = False +myst_enable_extensions = [ + "amsmath", + "colon_fence", + "dollarmath", + "strikethrough", +] +myst_update_mathjax = False +mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js" +nb_execution_excludepatterns = [ + "**.ipynb_checkpoints", + ".virtual_documents/*", + "lecture24_utilities.ipynb", +] +nb_execution_mode = get_execution_mode() +nb_execution_show_tb = True +nb_execution_timeout = -1 +suppress_warnings = [ + "mystnb.unknown_mime_type", +] diff --git a/environment.yml b/environment.yml index 81165f1..c6c7c3e 100644 --- a/environment.yml +++ b/environment.yml @@ -3,4 +3,4 @@ dependencies: - python==3.10.* - pip - pip: - - -r requirements.txt + - -e .[dev] diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..54e962b --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,170 @@ +[build-system] +build-backend = "setuptools.build_meta" +requires = [ + "setuptools>=61.2", + "setuptools_scm", +] + +[project] +authors = [ + {name = "Common Partial Wave Analysis", email = "compwa-admin@ep1.rub.de"}, + {name = "STRONG2020"}, +] +classifiers = [ + "Development Status :: 4 - Beta", + "Intended Audience :: Education", + "Intended Audience :: Science/Research", + "Natural Language :: English", + "Operating System :: OS Independent", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.7", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python", + "Topic :: Scientific/Engineering :: Physics", + "Topic :: Scientific/Engineering", +] +description = "Jupyter notebooks for the STRONG2020 school in Salamanca, 2023" +dynamic = ["version"] +name = "strong2020-salamanca" +requires-python = ">=3.7" + +[project.optional-dependencies] +dev = [ + "sphinx-autobuild", + "strong2020-salamanca[doc]", + "strong2020-salamanca[jupyter]", + "strong2020-salamanca[sty]", + "strong2020-salamanca[test]", + "tox", +] +doc = [ + "ipympl", + "myst-nb", + "sphinx-book-theme", + "sphinx-comments", + "sphinx-copybutton", + "sphinx-design", + "sphinx-exercise", + "sphinx-external-toc", + "sphinx-togglebutton", +] +format = [ + "black", + "isort", +] +jupyter = [ + "jupyterlab", + "jupyterlab-code-formatter", + "jupyterlab-lsp", + "jupyterlab-myst", + "python-lsp-server[flake8,rope]", +] +sty = [ + "pre-commit", + "strong2020-salamanca[format]", +] +test = ["nbmake"] + +[tool.tomlsort] +all = false +ignore_case = true +in_place = true +sort_first = [ + "build-system", + "project", + "tool.setuptools", + "tool.setuptools_scm", +] +sort_table_keys = true +spaces_indent_inline_array = 4 +trailing_comma_inline_array = true + +[tool.tox] +legacy_tox_ini = """ + [tox] + envlist = + doc, + sty, + skip_install = True + skip_missing_interpreters = True + skipsdist = True + + [testenv:doc] + allowlist_externals = + sphinx-build + commands = + sphinx-build \ + --keep-going \ + -TW \ + -b html \ + docs/ docs/_build/html + description = + Build documentation and API through Sphinx + passenv = * + setenv = + FORCE_COLOR = yes + + [testenv:doclive] + allowlist_externals = + sphinx-autobuild + commands = + sphinx-autobuild \ + --open-browser \ + --re-ignore docs/_build/.* \ + --watch docs \ + docs/ docs/_build/html + description = + Set up a server to directly preview changes to the HTML pages + passenv = * + setenv = + FORCE_COLOR = yes + + [testenv:docnb] + allowlist_externals = + sphinx-build + commands = + sphinx-build \ + --keep-going \ + -TW \ + -b html \ + docs/ docs/_build/html + description = + Build documentation through Sphinx WITH output of Jupyter notebooks + passenv = * + setenv = + EXECUTE_NB = yes + FORCE_COLOR = yes + + [testenv:docnb-force] + allowlist_externals = + sphinx-build + commands = + sphinx-build -nW --keep-going -b html docs/ docs/_build/html + description = + Execute ALL Jupyter notebooks and build documentation with Sphinx + passenv = * + setenv = + FORCE_COLOR = yes + FORCE_EXECUTE_NB = yes + + [testenv:nb] + allowlist_externals = + pytest + commands = + pytest --nbmake {posargs:docs} + description = + Run all notebooks with pytest + passenv = * + setenv = + + [testenv:sty] + allowlist_externals = + pre-commit + commands = + pre-commit run {posargs} -a + description = + Perform all linting, formatting, and spelling checks +""" diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index c453a65..0000000 --- a/requirements.txt +++ /dev/null @@ -1,12 +0,0 @@ -black -ipympl -isort -jupyter-book -jupyterlab -jupyterlab-code-formatter -jupyterlab-lsp -jupyterlab-myst -nbmake -pre-commit -python-lsp-server[flake8,rope] -sphinx-exercise