fix: packaging as well as rST & md document generation

- updates gh-action versions
- moves `docs/references` to `docs/api`
- ignores all `.md` files for Sphinx build
- includes `rST` docs in source control and `sdist`
- fixes all Sphinx doc generation warnings/errors
- removes `pyaml` & `twine` from dev dependencies

Author: yozachar

.github/workflows/docs.yaml.bkp

@@ -15,10 +15,10 @@ jobs:
     steps:
       # checkout repository
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       # set up specific python version
       - name: Set up Python v3.12
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.12"
       # building
@@ -30,10 +30,10 @@ jobs:
         run: python package/export docs
       # set up Pages
       - name: Set up Pages
-        uses: actions/configure-pages@v3
+        uses: actions/configure-pages@v4
       # upload static page
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@v3
         with:
           path: ${{ env.BUILD_PATH }}/site
   deploy:
@@ -50,4 +50,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v4

.github/workflows/package.yaml renamed to .github/workflows/package.yaml.bkp

@@ -16,10 +16,10 @@ jobs:
     steps:
       # checkout repository
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       # set up specific python version
       - name: Set up Python v3.8
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.8"
       # install dependencies
@@ -38,7 +38,7 @@ jobs:
           deactivate
       # upload package as artifact
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@v3
         with:
           path: ${{ env.BUILD_PATH }}/dist
   publish:

.github/workflows/pycqa.yaml

@@ -14,10 +14,10 @@ jobs:
     steps:
       # checkout repository
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       # set up specific python version
       - name: Set up Python v3.8
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.8"
       # tooling
@@ -41,10 +41,10 @@ jobs:
       # checkout repository again!
       # ref: https://github.com/actions/checkout/issues/19
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       # set up specific python version
       - name: Set up Python v${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"

.github/workflows/sast.yaml

@@ -16,9 +16,9 @@ jobs:
       actions: read # only required for a private repository by github/codeql-action/upload-sarif to get the Action run status
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Bandit
-        uses: mdegis/bandit-action@85fcc340c3b0bf5d86029abb49b9aac916d807b2
+        uses: mdegis/bandit-action@851671cb116c1d3638de86975006bddf2619362a
         with:
           # exit with 0, even with results found
           # exit_zero: true # optional, default is DEFAULT

.gitignore

@@ -69,11 +69,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-# docs/references/
 docs/_build/
-# temporary
-docs/references/*.rst
-docs/*.rst
 docs/*.1
 
 # PyBuilder

CHANGES.md

@@ -1,21 +1,31 @@
 # MANIFEST.in stays as long as pyproject.toml does not officially support it
 # https://packaging.python.org/en/latest/specifications/declaring-project-metadata/
 
-include docs/*
-include .gitignore
+# include
+include CHANGES.md
+include mkdocs.yaml
+
 
 # global-include
 
+
+# recursive-include
 recursive-include tests *
+recursive-include docs *
+
 
 # graft
 
+
 # exclude
 
+
 # global-exclude
 
-recursive-exclude docs *.rst
-recursive-exclude docs/references *.md
 
+# recursive-exclude
+
+
+# prune
 prune docs/_build
 prune **/__pycache__