build!: upgrade and reorganize dependencies (#51)

* build: set Development Status to Pre-Alpha
* chore: put application imports on separate line
* chore: reorganize .gitignores
* ci: add doc-live tox job
* ci: ignore _build in pyright
* docs: add General Index and Search
* docs: add Table of Contents header
* docs: add favicon
* docs: add link to contribute page
* docs: add maintainer email
* docs: generalize conf.py through package name
* docs: remove API page layer
* docs: use repo_name in conf.py
* fix: cspell errors prereleased
* fix: deactivate pytest color for VSCode
* fix: ignore numpy and matplotlib types
* fix: install version.py under correct path
* fix: only extract doc version if available

.editorconfig

@@ -9,9 +9,6 @@ insert_final_newline = true
 [Makefile]
 indent_style = tab
 
-[Makefile]
-indent_style = tab
-
 [*.{py,toml}]
 indent_size = 4
 

.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

.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

.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

.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

.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

.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
 }

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)

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",

docs/.gitignore

@@ -2,4 +2,3 @@
 *.inv
 *build/
 api/
-pwa_pages.svg

docs/conf.py

@@ -18,19 +18,22 @@
 
 # -- 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)
 subprocess.call(
     " ".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,17 +199,18 @@
             [
                 "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",
             ]
         ),
         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):

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 <software:Sub-projects>`.
 
+## Table of Contents
+
 ```{toctree}
 ---
 maxdepth: 2
@@ -41,16 +43,12 @@ theory
 analysis
 software
 develop
+API <api/pwa_pages>
 ```
 
 - {ref}`Python API <modindex>`
-
-```{toctree}
----
-hidden:
----
-api
-```
+- {ref}`General Index <genindex>`
+- {ref}`Search <search>`
 
 ```{toctree}
 ---

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

pyrightconfig.json

@@ -1,5 +1,5 @@
 {
-  "exclude": [".git", ".tox"],
+  "exclude": [".git", ".tox", "docs/_build"],
   "include": ["docs", "src", "tests"],
   "reportGeneralTypeIssues": false,
   "reportUnboundVariable": false,