diff --git a/.editorconfig b/.editorconfig index e3481199..0ae391f4 100644 --- a/.editorconfig +++ b/.editorconfig @@ -9,9 +9,6 @@ insert_final_newline = true [Makefile] indent_style = tab -[Makefile] -indent_style = tab - [*.{py,toml}] indent_size = 4 diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml index 8115518e..a23ea0e7 100644 --- a/.github/workflows/cd.yml +++ b/.github/workflows/cd.yml @@ -1,11 +1,12 @@ -# cspell:ignore noreply pypa sdist +# cspell:ignore noreply prereleased pypa name: CD on: - create: - tags: - - "[0-9]+.[0-9]+.[0-9]+*" + release: + types: + - prereleased + - released jobs: documentation: @@ -45,10 +46,10 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install .[ci] + pip install .[precommit] sudo npm install -g cspell markdownlint-cli pyright - name: Perform style checks - run: tox -e sty + run: pre-commit run -a - name: Check spelling run: cspell $(git ls-files) - name: Lint Markdown files diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d089da2f..290d8bdc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -46,10 +46,10 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install .[ci] + pip install .[precommit] sudo npm install -g cspell markdownlint-cli pyright - name: Perform style checks - run: tox -e sty + run: pre-commit run -a - name: Check spelling run: cspell $(git ls-files) - name: Lint Markdown files diff --git a/.gitignore b/.gitignore index 524b7b92..c30a66c1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,14 @@ +# Output files +*.gv +*.json +*.npy +*.pdf +*.png +*.svg +*.xml +*.yaml +*.yml + # Build files *.egg-info/ *build/ @@ -26,3 +37,16 @@ pyvenv*/ # Settings .idea/ **.code-workspace + +# Exceptions +!.github/*.yml +!.github/*/*.yml +!.gitpod.yml +!.markdownlint.json +!.pre-commit-config.yaml +!.readthedocs.yml +!.vscode/*.json +!codecov.yml +!cspell.json +!environment.yml +!pyrightconfig.json diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 448ea360..86634721 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -9,7 +9,6 @@ repos: hooks: - id: check-ast - id: check-case-conflict - - id: check-docstring-first - id: check-json - id: check-merge-conflict - id: check-toml @@ -25,8 +24,8 @@ repos: - id: mixed-line-ending - id: trailing-whitespace - - repo: https://github.com/prettier/prettier - rev: 2.1.2 + - repo: https://github.com/pre-commit/mirrors-prettier + rev: v2.2.0 hooks: - id: prettier language_version: 12.18.2 # prettier does not specify node correctly diff --git a/.pylintrc b/.pylintrc index a0ef315b..5bca367a 100644 --- a/.pylintrc +++ b/.pylintrc @@ -21,5 +21,11 @@ disable= ignore= conf.py +[DESIGN] +# Minimum number of public methods for a class (see R0903). Default is 2. +# We decrease this to 0, since some rules are "empty" but get decorated. +# Note that some interface classes also just have a single method +min-public-methods=0 + [SIMILARITIES] ignore-imports=yes # https://stackoverflow.com/a/30007053 diff --git a/.vscode/settings.json b/.vscode/settings.json index ad0de1aa..5da95153 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -51,11 +51,17 @@ "python.linting.pylintEnabled": true, "python.linting.pylintUseMinimalCheckers": false, "python.testing.nosetestsEnabled": false, + "python.testing.pytestArgs": ["--color=no", "--no-cov"], "python.testing.pytestEnabled": false, "python.testing.unittestEnabled": false, "restructuredtext.builtDocumentationPath": "${workspaceFolder}/docs/_build/html", - "restructuredtext.confPath": "${workspaceFolder}/doc", + "restructuredtext.confPath": "${workspaceFolder}/docs", "rewrap.wrappingColumn": 79, + "search.exclude": { + "**/tests/**/__init__.py": true, + "docs/tox.ini": true, + "tests/tox.ini": true + }, "telemetry.enableCrashReporter": false, "telemetry.enableTelemetry": false } diff --git a/README.md b/README.md index 3092f6a6..9c82f343 100644 --- a/README.md +++ b/README.md @@ -12,3 +12,7 @@ This repository contains the source code for the [pwa.rtfd.io](https://pwa.readthedocs.io) pages. + +## Contribute + +See [`CONTRIBUTING.md`](./CONTRIBUTING.md) diff --git a/cspell.json b/cspell.json index 611dd479..42f419fd 100644 --- a/cspell.json +++ b/cspell.json @@ -28,6 +28,7 @@ ".vscode/*", ".vscode/.gitignore", "Makefile", + "codecov.yml", "cspell.json", "docs/_templates/*", "docs/conf.py", @@ -99,6 +100,7 @@ "oneline", "pandoc", "pawian", + "precommit", "propto", "pycompwa", "pydocstyle", diff --git a/docs/.gitignore b/docs/.gitignore index 0209b04a..b6c50e96 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -2,4 +2,3 @@ *.inv *build/ api/ -pwa_pages.svg diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 00000000..bfd192b1 Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/api.rst b/docs/api.rst deleted file mode 100644 index 4b3ede42..00000000 --- a/docs/api.rst +++ /dev/null @@ -1,14 +0,0 @@ -API -=== - -The PWA pages contains a few functions that can be used in the Jupyter -notebooks that underlie these pages. - -.. toctree:: - - api/pwa_pages - -.. seealso:: - - * :ref:`modindex` - * :ref:`genindex` diff --git a/docs/conf.py b/docs/conf.py index 657d5b21..573a4398 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,11 +18,14 @@ # -- Project information ----------------------------------------------------- project = "PWA Software Pages" +package = "pwa_pages" +repo_name = "PWA-pages" copyright = "2020, ComPWA" author = "Common Partial Wave Analysis" -__release = get_distribution("pwa_pages").version -version = ".".join(__release.split(".")[:3]) +if os.path.exists(f"../src/{package}/version.py"): + __release = get_distribution(package).version + version = ".".join(__release.split(".")[:3]) # -- Generate API skeleton ---------------------------------------------------- shutil.rmtree("api", ignore_errors=True) @@ -30,7 +33,7 @@ " ".join( [ "sphinx-apidoc", - "../src/pwa_pages/", + f"../src/{package}/", "-o api/", "--force", "--no-toc", @@ -53,7 +56,7 @@ # The master toctree document. master_doc = "index" modindex_common_prefix = [ - "pwa_pages.", + f"{package}.", ] extensions = [ @@ -94,17 +97,18 @@ ), } html_copy_source = True # needed for download notebook button +html_favicon = "_static/favicon.ico" html_show_copyright = False html_show_sourcelink = False html_show_sphinx = False html_sourcelink_suffix = "" html_theme = "sphinx_book_theme" html_theme_options = { - "repository_url": "https://github.com/ComPWA/PWA-pages", + "repository_url": f"https://github.com/ComPWA/{repo_name}", "repository_branch": "stable", "path_to_docs": "docs", - "use_edit_page_button": True, "use_download_button": True, + "use_edit_page_button": True, "use_issues_button": True, "use_repository_button": True, "launch_buttons": { @@ -125,7 +129,6 @@ default_role = "py:obj" primary_domain = "py" nitpicky = True # warn if cross-references are missing -nitpick_ignore = [] # Intersphinx settings intersphinx_mapping = { @@ -196,7 +199,8 @@ [ "HOME=.", # in case of calling through tox "pydeps", - "../src/pwa_pages", + f"../src/{package}", + "-o module_structure.svg", "--exclude *._*", # hide private modules "--max-bacon=2", # hide external dependency submodules "--noshow", @@ -204,9 +208,9 @@ ), shell=True, ) - if os.path.exists("pwa_pages.svg"): - with open("api/pwa_pages.rst", "a") as stream: - stream.write("\n.. image:: /pwa_pages.svg") + if os.path.exists("module_structure.svg"): + with open(f"api/{package}.rst", "a") as stream: + stream.write("\n.. image:: /module_structure.svg") # Add roles to simplify external linnks def setup(app: Sphinx): diff --git a/docs/index.md b/docs/index.md index 0cef6021..2d1a060c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,6 +33,8 @@ the available software tools that are relevant to PWA software development. Finally, the [develop page](./develop.md) formulates some conventions and tools that are used by {ref}`affiliated software packages `. +## Table of Contents + ```{toctree} --- maxdepth: 2 @@ -41,16 +43,12 @@ theory analysis software develop +API ``` - {ref}`Python API ` - -```{toctree} ---- -hidden: ---- -api -``` +- {ref}`General Index ` +- {ref}`Search ` ```{toctree} --- diff --git a/pyproject.toml b/pyproject.toml index 10639bb9..52a0e183 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ requires = [ ] [tool.setuptools_scm] -write_to = "pwa_pages/version.py" +write_to = "src/pwa_pages/version.py" [tool.black] line-length = 79 diff --git a/pyrightconfig.json b/pyrightconfig.json index 0036b13f..bbad5e89 100644 --- a/pyrightconfig.json +++ b/pyrightconfig.json @@ -1,5 +1,5 @@ { - "exclude": [".git", ".tox"], + "exclude": [".git", ".tox", "docs/_build"], "include": ["docs", "src", "tests"], "reportGeneralTypeIssues": false, "reportUnboundVariable": false, diff --git a/setup.cfg b/setup.cfg index ff513e94..5b77ef88 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,7 +1,11 @@ [metadata] name = PWA-pages +author = Common Partial Wave Analysis +author_email = compwa-admin@ep1.rub.de +maintainer_email = compwa-admin@ep1.rub.de long_description = file: README.md long_description_content_type = text/markdown +# URLS are shown in reverse order on PyPI project_urls = Tracker = https://github.com/ComPWA/PWA-pages/issues Changelog = https://github.com/ComPWA/PWA-pages/releases @@ -17,7 +21,7 @@ keywords = particles physics classifiers = - Development Status :: 1 - Planning + Development Status :: 2 - Pre-Alpha Intended Audience :: Developers Intended Audience :: Education Intended Audience :: Science/Research @@ -52,13 +56,13 @@ pwa_pages = [options.extras_require] doc = - graphviz==0.14.2 + graphviz==0.15 ipywidgets==7.5.1 jupyter==1.0.0 myst-nb==0.10.1 pybtex==0.23.0 pydeps==1.9.11 - Sphinx==3.2.1 + Sphinx==3.3.1 sphinx-book-theme==0.0.39 sphinx-copybutton==0.3.1 sphinx-math-dollar==1.2 @@ -68,36 +72,40 @@ doc = sphinxcontrib-bibtex==1.0.0 format = black==20.8b1 - isort==5.6.1 -lint = - data-science-types==0.2.19 + isort==5.6.4 + nbstripout==0.3.9 +lint-doc = doc8==0.8.1 - flake8==3.8.3 # >=3 for per-file-ignores + rstcheck==3.3.1 +lint-py = + flake8==3.8.4 flake8-blind-except==0.1.1 flake8-bugbear==20.1.4 flake8-builtins==1.5.3 - flake8-rst-docstrings==0.0.13 - mypy==0.782 - nbstripout==0.3.8 + flake8-rst-docstrings==0.0.14 + mypy==0.790 pep8-naming==0.11.1 pydocstyle==5.1.1 pylint==2.6.0 - rstcheck==3.3.1 -ci = +lint = + %(lint-doc)s + %(lint-py)s +precommit = %(format)s %(lint)s pre-commit==2.8.2 - tox==3.20.0 +tox = + %(precommit)s + sphinx-autobuild==2020.9.1 + tox==3.20.1 tools = - jupyterlab==2.2.4 + jupyterlab==2.2.9 jupyterlab_code_formatter==1.3.6 - jupyter_nbextensions_configurator==0.4.1 labels==20.1.0 - sphinx-autobuild==2020.9.1 dev = - %(ci)s %(doc)s %(tools)s + %(tox)s [doc8] extension=.inc @@ -114,10 +122,11 @@ files = **/*.py, **/*.pyi, -[mypy-conf.*] -ignore = True - ; External packages that miss stubs or type hints +[mypy-matplotlib.*] +ignore_missing_imports = True +[mypy-numpy.*] +ignore_missing_imports = True [mypy-setuptools.*] ignore_missing_imports = True diff --git a/tox.ini b/tox.ini index 9a1cf275..f13f44d2 100644 --- a/tox.ini +++ b/tox.ini @@ -16,15 +16,6 @@ whitelist_externals = commands = make html -[testenv:linkcheck] -description = - Check external links in the documentation (requires internet connection) -changedir = docs -whitelist_externals = - make -commands = - make ignore-warnings=1 linkcheck # for margin directive - [testenv:doc-live] description = Set up a server to preview changes to the HTML pages live @@ -34,11 +25,22 @@ commands = sphinx-autobuild \ --watch docs \ --watch src \ - --re-ignore docs/api/.* \ + --re-ignore docs/.*\.inv \ --re-ignore docs/_build/.* \ + --re-ignore docs/api/.* \ --open-browser \ docs/ docs/_build/html + +[testenv:linkcheck] +description = + Check external links in the documentation (requires internet connection) +changedir = docs +whitelist_externals = + make +commands = + make ignore-warnings=1 linkcheck # for margin directive + [testenv:sty] description = Perform all linting, formatting, and spelling checks @@ -55,7 +57,8 @@ commands = - bash -ec "markdownlint . --ignore docs/_build" [flake8] -application-import-names = pwa_pages +application-import-names = + pwa_pages filename = ./src/*.py exclude =