From c8903d169118c76e4d711434a1a7871ca97017c6 Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 11 Nov 2024 07:52:57 +0100 Subject: [PATCH 01/59] Initial commit --- .gitignore | 162 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 + 2 files changed, 164 insertions(+) create mode 100644 .gitignore create mode 100644 README.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..82f9275 --- /dev/null +++ b/.gitignore @@ -0,0 +1,162 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# poetry +# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. +# This is especially recommended for binary packages to ensure reproducibility, and is more +# commonly ignored for libraries. +# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control +#poetry.lock + +# pdm +# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. +#pdm.lock +# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it +# in version control. +# https://pdm.fming.dev/latest/usage/project/#working-with-version-control +.pdm.toml +.pdm-python +.pdm-build/ + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +# JetBrains specific template is maintained in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +#.idea/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..6096c31 --- /dev/null +++ b/README.md @@ -0,0 +1,2 @@ +# template-python +Template repository for python projects From 8fd8ad968227604fd598d2fe65654d7535008875 Mon Sep 17 00:00:00 2001 From: maxlin-ipp Date: Tue, 12 Nov 2024 19:32:56 +0100 Subject: [PATCH 02/59] Wrote some basic python setup. --- .gitignore | 6 ++++++ README.md | 28 ++++++++++++++++++++++++++++ pyproject.toml | 33 +++++++++++++++++++++++++++++++++ src/app/main.py | 2 ++ 4 files changed, 69 insertions(+) create mode 100644 pyproject.toml create mode 100644 src/app/main.py diff --git a/.gitignore b/.gitignore index 82f9275..3dba600 100644 --- a/.gitignore +++ b/.gitignore @@ -160,3 +160,9 @@ cython_debug/ # and can be added to the global gitignore or merged into this file. For a more nuclear # option (not recommended) you can uncomment the following to ignore the entire idea folder. #.idea/ + + +.vscode/ + +# Hidden files +.DS_Store \ No newline at end of file diff --git a/README.md b/README.md index 6096c31..7486ed9 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,30 @@ # template-python Template repository for python projects + +# Install + +Create and activate python environment + +``` +python -m venv env +source env/bin/activate +pip install --upgrade pip +``` + +Install the code and requirements with pip + +``` +pip install -e . +``` + +Run the code with + +``` +app +``` + +For help message, run + +``` +app -h +``` \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..c2aeca0 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,33 @@ +[build-system] +requires = ["setuptools", "wheel"] +build-backend = "setuptools.build_meta" + +[project] +name = "template-python" +version = "0.1" +description = "Template python repository." +readme = "README.md" +requires-python = ">=3.8" +license = {file = "LICENSE.txt"} +keywords = ["python"] +authors = [{name = "Max"}] +classifiers = [ + "Development Status :: 3 - Alpha", +] +dependencies = [ + "black", + "isort", + "autopep8", +] + +[project.optional-dependencies] +dev = ["check-manifest"] +test = ["coverage"] +[project.urls] +"Source" = "https://github.com/max-models/template-python" + +[tool.setuptools.packages.find] +where = ["src"] + +[project.scripts] +template-python = "app.main:main" diff --git a/src/app/main.py b/src/app/main.py new file mode 100644 index 0000000..dd58fb6 --- /dev/null +++ b/src/app/main.py @@ -0,0 +1,2 @@ +def main(): + print('Hello, world') \ No newline at end of file From 71367247ad1a20411e2094710ddb4f07c0adf055 Mon Sep 17 00:00:00 2001 From: maxlin-ipp Date: Tue, 12 Nov 2024 19:33:56 +0100 Subject: [PATCH 03/59] Update to README.md --- README.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/README.md b/README.md index 7486ed9..43221df 100644 --- a/README.md +++ b/README.md @@ -20,11 +20,5 @@ pip install -e . Run the code with ``` -app -``` - -For help message, run - -``` -app -h +template-python ``` \ No newline at end of file From 11f5994bab0e15f4a9a8e1910f2e33ded8244a9d Mon Sep 17 00:00:00 2001 From: maxlin-ipp Date: Tue, 12 Nov 2024 19:49:06 +0100 Subject: [PATCH 04/59] Add src/*.egg-info/ to .gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 3dba600..7f56173 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,7 @@ var/ wheels/ share/python-wheels/ *.egg-info/ +src/*.egg-info/ .installed.cfg *.egg MANIFEST From 8e518b81374daebbc6a215ccc32e42d37e709ea0 Mon Sep 17 00:00:00 2001 From: maxlin-ipp Date: Sun, 17 Nov 2024 19:28:48 +0100 Subject: [PATCH 05/59] Update to gitignore --- .gitignore | 6 +++++- pytest.ini | 2 ++ tests/unit/__init__.py | 0 tests/unit/test_app.py | 7 +++++++ 4 files changed, 14 insertions(+), 1 deletion(-) create mode 100644 pytest.ini create mode 100644 tests/unit/__init__.py create mode 100644 tests/unit/test_app.py diff --git a/.gitignore b/.gitignore index 7f56173..99ffb91 100644 --- a/.gitignore +++ b/.gitignore @@ -166,4 +166,8 @@ cython_debug/ .vscode/ # Hidden files -.DS_Store \ No newline at end of file +.DS_Store +.pymon + +# Unit test output +junit/ diff --git a/pytest.ini b/pytest.ini new file mode 100644 index 0000000..fa4a21d --- /dev/null +++ b/pytest.ini @@ -0,0 +1,2 @@ +[pytest] +pythonpath = src diff --git a/tests/unit/__init__.py b/tests/unit/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/unit/test_app.py b/tests/unit/test_app.py new file mode 100644 index 0000000..386da12 --- /dev/null +++ b/tests/unit/test_app.py @@ -0,0 +1,7 @@ +def test_import_app(): + from app.main import main + print('app imported') + main() + +if __name__ == '__main__': + test_import_app() \ No newline at end of file From 3109612f4654647e46a7be3062633c51cc76209e Mon Sep 17 00:00:00 2001 From: maxlin-ipp Date: Sun, 17 Nov 2024 19:30:13 +0100 Subject: [PATCH 06/59] Added CI --- .github/workflows/ci.yml | 72 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..cabb162 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,72 @@ +name: CI + +on: + push: + branches: + - main + - devel + pull_request: + branches: + - main + - devel + +jobs: + build: + runs-on: ubuntu-latest + + steps: + # Checkout the repository + - name: Checkout code + uses: actions/checkout@v3 + + # Set up Python + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' # Adjust as needed + + # Cache pip dependencies + - name: Cache pip + uses: actions/cache@v3 + with: + path: ~/.cache/pip + key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }} + restore-keys: | + ${{ runner.os }}-pip- + + # Create virtual environment and install project from pyproject.toml + - name: Set up virtual environment and install project + run: | + python -m venv env + source env/bin/activate + pip install --upgrade pip + pip install . + + # Run a basic command to check installation + - name: Check installation + run: | + source env/bin/activate + src/app -h + + # Run tests + - name: Run tests + run: | + source env/bin/activate + pytest --doctest-modules --junitxml=junit/test-results.xml + env: + CI: true + + # Upload test results + - name: Upload test results + if: always() + uses: actions/upload-artifact@v3 + with: + name: test-results + path: junit/test-results.xml + + # Code formatting check with black + - name: Code formatting with black + run: | + source env/bin/activate + pip install black + black --check src/ From 2ebc6d3f935b51761fce58e40b70449404ae5bac Mon Sep 17 00:00:00 2001 From: maxlin-ipp Date: Sun, 17 Nov 2024 19:32:07 +0100 Subject: [PATCH 07/59] Bugfixes in CI --- .github/workflows/ci.yml | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cabb162..7996e6e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -46,24 +46,16 @@ jobs: - name: Check installation run: | source env/bin/activate - src/app -h + template-python # Run tests - name: Run tests run: | source env/bin/activate - pytest --doctest-modules --junitxml=junit/test-results.xml + pytest . env: CI: true - # Upload test results - - name: Upload test results - if: always() - uses: actions/upload-artifact@v3 - with: - name: test-results - path: junit/test-results.xml - # Code formatting check with black - name: Code formatting with black run: | From 2389e39815a4dee88e0a315b94a842229c5ea20e Mon Sep 17 00:00:00 2001 From: maxlin-ipp Date: Sun, 17 Nov 2024 19:34:22 +0100 Subject: [PATCH 08/59] Formatting --- src/app/main.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/app/main.py b/src/app/main.py index dd58fb6..a801985 100644 --- a/src/app/main.py +++ b/src/app/main.py @@ -1,2 +1,2 @@ def main(): - print('Hello, world') \ No newline at end of file + print("Hello, world") From b849d81be477776fdd628d3b4d504044377974d5 Mon Sep 17 00:00:00 2001 From: maxlin-ipp Date: Sun, 17 Nov 2024 19:34:42 +0100 Subject: [PATCH 09/59] Added pytest to pyproject.toml reqs --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index c2aeca0..5448f13 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -18,6 +18,7 @@ dependencies = [ "black", "isort", "autopep8", + "pytest", ] [project.optional-dependencies] From 0e16d321e8cfcc0814eee7a80dddea964887c226 Mon Sep 17 00:00:00 2001 From: maxlin-ipp Date: Sun, 17 Nov 2024 19:55:37 +0100 Subject: [PATCH 10/59] formatting --- tests/unit/test_app.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/tests/unit/test_app.py b/tests/unit/test_app.py index 386da12..5e9299e 100644 --- a/tests/unit/test_app.py +++ b/tests/unit/test_app.py @@ -1,7 +1,9 @@ def test_import_app(): from app.main import main - print('app imported') + + print("app imported") main() -if __name__ == '__main__': - test_import_app() \ No newline at end of file + +if __name__ == "__main__": + test_import_app() From bf5a16d08e72cf7ffebdbf64c1a2b600201f0726 Mon Sep 17 00:00:00 2001 From: maxlin-ipp Date: Sun, 17 Nov 2024 19:55:46 +0100 Subject: [PATCH 11/59] added isort --- .github/workflows/ci.yml | 3 +++ pyproject.toml | 1 - 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7996e6e..9d2db1c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -61,4 +61,7 @@ jobs: run: | source env/bin/activate pip install black + pip install isort black --check src/ + isort --check src/ + diff --git a/pyproject.toml b/pyproject.toml index 5448f13..d8b3042 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -17,7 +17,6 @@ classifiers = [ dependencies = [ "black", "isort", - "autopep8", "pytest", ] From fd205a45cc141b7e556519e40b8eb0425a4a001a Mon Sep 17 00:00:00 2001 From: maxlin-ipp Date: Sun, 17 Nov 2024 20:07:45 +0100 Subject: [PATCH 12/59] Small rename in CI --- .github/workflows/ci.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9d2db1c..fac5f3a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -57,11 +57,10 @@ jobs: CI: true # Code formatting check with black - - name: Code formatting with black + - name: Code formatting with black and isort run: | source env/bin/activate pip install black pip install isort black --check src/ isort --check src/ - From b8d0c1bb90c45bcd34f6579244a133b3f53e7ec8 Mon Sep 17 00:00:00 2001 From: maxlin-ipp Date: Tue, 11 Feb 2025 22:04:59 +0100 Subject: [PATCH 13/59] Lint in separate job --- .github/workflows/ci.yml | 40 +++++++++++++++++++++++++++++++++++----- 1 file changed, 35 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fac5f3a..3b0f475 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -55,12 +55,42 @@ jobs: pytest . env: CI: true + + # Linting job + lint: + runs-on: ubuntu-latest + + steps: + # Checkout the repository + - name: Checkout code + uses: actions/checkout@v3 + + # Set up Python + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + + # Cache pip dependencies + - name: Cache pip + uses: actions/cache@v3 + with: + path: ~/.cache/pip + key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }} + restore-keys: | + ${{ runner.os }}-pip- + + # Install linting tools + - name: Install linting tools + run: | + python -m venv env + source env/bin/activate + pip install --upgrade pip + pip install black isort - # Code formatting check with black - - name: Code formatting with black and isort + # Code formatting check with black and isort + - name: Run linters run: | source env/bin/activate - pip install black - pip install isort black --check src/ - isort --check src/ + isort --check src/ \ No newline at end of file From 96dedf579b4d034e720f26c195ae04526f4b8e76 Mon Sep 17 00:00:00 2001 From: maxlin-ipp Date: Sun, 9 Mar 2025 19:38:58 +0100 Subject: [PATCH 14/59] Added .gitattributes --- .gitattributes | 1 + 1 file changed, 1 insertion(+) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..2f41707 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +*.ipynb filter=strip-notebook-output From dc74d9975d7fcf660256d641dd78ebf8b072668f Mon Sep 17 00:00:00 2001 From: Max Lindqvist Date: Wed, 16 Apr 2025 16:02:42 +0200 Subject: [PATCH 15/59] Added .gitlab-ci.yml --- .gitlab-ci.yml | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 .gitlab-ci.yml diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml new file mode 100644 index 0000000..7de373c --- /dev/null +++ b/.gitlab-ci.yml @@ -0,0 +1,57 @@ +# This file is a template, and might need editing before it works on your project. +# To contribute improvements to CI/CD templates, please follow the Development guide at: +# https://docs.gitlab.com/ee/development/cicd/templates.html +# This specific template is located at: +# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Python.gitlab-ci.yml + +# Official language image. Look for the different tagged releases at: +# https://hub.docker.com/r/library/python/tags/ +image: python:latest + +# Change pip's cache directory to be inside the project directory since we can +# only cache local items. +variables: + PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip" + +# https://pip.pypa.io/en/stable/topics/caching/ +cache: + paths: + - .cache/pip + +before_script: + - python --version ; pip --version # For debugging + - pip install virtualenv + - virtualenv venv + - source venv/bin/activate + +test: + script: + - pip install ruff tox # you can also use tox + - pip install --editable ".[test]" + - tox -e py,ruff + +run: + script: + - pip install . + # run the command here + artifacts: + paths: + - build/* + +pages: + script: + - pip install sphinx sphinx-rtd-theme + - cd doc + - make html + - mv build/html/ ../public/ + artifacts: + paths: + - public + rules: + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + +deploy: + stage: deploy + script: echo "Define your deployment script!" + environment: production + From 2299cc0eb4088e8d78ec59d39ba5caf49b3cf235 Mon Sep 17 00:00:00 2001 From: Max Date: Fri, 18 Apr 2025 12:14:38 +0200 Subject: [PATCH 16/59] Updated optional dependencies --- pyproject.toml | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index d8b3042..839616a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -15,14 +15,19 @@ classifiers = [ "Development Status :: 3 - Alpha", ] dependencies = [ + "numpy", +] + +[project.optional-dependencies] +test = ["pytest", "coverage"] +dev = [ + "template-python[test]", "black", "isort", + "ruff", "pytest", ] -[project.optional-dependencies] -dev = ["check-manifest"] -test = ["coverage"] [project.urls] "Source" = "https://github.com/max-models/template-python" From 387c61102c18e552eee40c91855d8a43571f3efe Mon Sep 17 00:00:00 2001 From: Max Date: Fri, 18 Apr 2025 12:18:23 +0200 Subject: [PATCH 17/59] Extended the static analysis in job in the CI --- .github/workflows/ci.yml | 70 +++++++++++++++++++++++----------------- 1 file changed, 40 insertions(+), 30 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3b0f475..155b3c2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -56,41 +56,51 @@ jobs: env: CI: true - # Linting job - lint: + # Static analysis + static-analysis: runs-on: ubuntu-latest - steps: - # Checkout the repository - - name: Checkout code - uses: actions/checkout@v3 + - name: Checkout the code + uses: actions/checkout@v4 - # Set up Python - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: '3.10' + - name: Download and run cloc + run: | + curl -s https://raw.githubusercontent.com/AlDanial/cloc/master/cloc > cloc + chmod +x cloc + ./cloc --version + ./cloc $(git ls-files) - # Cache pip dependencies - - name: Cache pip - uses: actions/cache@v3 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }} - restore-keys: | - ${{ runner.os }}-pip- + - name: Code formatting with black + run: | + pip install black + pip install "black[jupyter]" + black --check src/ - # Install linting tools - - name: Install linting tools + - name: Code formatting with isort run: | - python -m venv env - source env/bin/activate - pip install --upgrade pip - pip install black isort + pip install isort + isort --check src/ - # Code formatting check with black and isort - - name: Run linters + - name: Code formatting with prospector + continue-on-error: true run: | - source env/bin/activate - black --check src/ - isort --check src/ \ No newline at end of file + pip install mypy + mypy src/ + + - name: Code formatting with prospector + continue-on-error: true + run: | + pip install prospector + prospector src/ + + - name: Code formatting with ruff + continue-on-error: true + run: | + pip install ruff + ruff check src/ + + - name: Code formatting with pylint + continue-on-error: true + run: | + pip install pylint + pylint src/ From 475c02c0c79ab9eafd87676240f7c531577497aa Mon Sep 17 00:00:00 2001 From: Max Date: Fri, 18 Apr 2025 12:21:08 +0200 Subject: [PATCH 18/59] Install with .[test] in the CI --- .github/workflows/ci.yml | 2 +- pyproject.toml | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 155b3c2..e41360c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -40,7 +40,7 @@ jobs: python -m venv env source env/bin/activate pip install --upgrade pip - pip install . + pip install ".[test]" # Run a basic command to check installation - name: Check installation diff --git a/pyproject.toml b/pyproject.toml index 839616a..358fb82 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -25,7 +25,6 @@ dev = [ "black", "isort", "ruff", - "pytest", ] [project.urls] From d405a6bcb0c3931ba8d7bbb281d5e31a6d099f7c Mon Sep 17 00:00:00 2001 From: Max Date: Fri, 18 Apr 2025 12:23:24 +0200 Subject: [PATCH 19/59] Added some docstrings --- src/app/main.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/app/main.py b/src/app/main.py index a801985..b24fcb8 100644 --- a/src/app/main.py +++ b/src/app/main.py @@ -1,2 +1,7 @@ +""" +Main module of the python package. +""" + def main(): + """Main method called from from the command line.""" print("Hello, world") From 308189415129991102d069a6c8b2dbfabcbe8dfb Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 20 Apr 2025 11:52:41 +0200 Subject: [PATCH 20/59] Added docs dependencies --- pyproject.toml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 358fb82..b7bfce9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -26,6 +26,11 @@ dev = [ "isort", "ruff", ] +# https://medium.com/@pratikdomadiya123/build-project-documentation-quickly-with-the-sphinx-python-2a9732b66594 +docs = [ + "sphinx", + "sphinx_rtd_theme", +] [project.urls] "Source" = "https://github.com/max-models/template-python" From 326fba46626a12774d5d5c2f1adbdebdeb3b8498 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 20 Apr 2025 11:52:57 +0200 Subject: [PATCH 21/59] Added docs --- docs/Makefile | 20 ++++++++++++++++++ docs/conf.py | 54 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 17 +++++++++++++++ docs/main.rst | 7 +++++++ docs/make.bat | 35 +++++++++++++++++++++++++++++++ docs/modules.rst | 7 +++++++ 6 files changed, 140 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/main.rst create mode 100644 docs/make.bat create mode 100644 docs/modules.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..0c2f42c --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,54 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html +import os +import sys + +# sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath("../src/app")) + + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "python-template" +copyright = "2025, Max" +author = "Max" + +# The full version, including alpha/beta/rc tags +release = "1.0.0" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + # 'myst_parser', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..e354a7c --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,17 @@ +.. python-template documentation master file, created by + sphinx-quickstart on Sun Apr 20 11:40:45 2025. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +python-template documentation +============================= + +Add your content using ``reStructuredText`` syntax. See the +`reStructuredText `_ +documentation for details. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + diff --git a/docs/main.rst b/docs/main.rst new file mode 100644 index 0000000..7874bd9 --- /dev/null +++ b/docs/main.rst @@ -0,0 +1,7 @@ +main module +=========== + +.. automodule:: main + :members: + :show-inheritance: + :undoc-members: diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/modules.rst b/docs/modules.rst new file mode 100644 index 0000000..6378a90 --- /dev/null +++ b/docs/modules.rst @@ -0,0 +1,7 @@ +app +=== + +.. toctree:: + :maxdepth: 4 + + main From 867379eda2949ee22bc5474e9d2f93c194a364d5 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 20 Apr 2025 11:53:08 +0200 Subject: [PATCH 22/59] Test building docs in CI --- .github/workflows/ci.yml | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e41360c..90b2063 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -55,7 +55,17 @@ jobs: pytest . env: CI: true - + + - name: Test docs build + run: | + pip install ".[docs]" + sphinx-apidoc -o docs src/app + cd docs + make clean + make html + cd .. + ls docs/_build/html/index.html + # Static analysis static-analysis: runs-on: ubuntu-latest @@ -104,3 +114,29 @@ jobs: run: | pip install pylint pylint src/ + docs: + runs-on: ubuntu-latest + + steps: + # Checkout the repository + - name: Checkout code + uses: actions/checkout@v3 + + # Set up Python + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' # Adjust as needed + + # Cache pip dependencies + - name: Cache pip + uses: actions/cache@v3 + with: + path: ~/.cache/pip + key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }} + restore-keys: | + ${{ runner.os }}-pip- + + - name: Test docs build + run: | + pip install ".[docs]" From 45b42f8daeacb9c63664238772990ecd1493f82d Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 20 Apr 2025 11:54:54 +0200 Subject: [PATCH 23/59] Formatting --- src/app/main.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/app/main.py b/src/app/main.py index b24fcb8..063d2ee 100644 --- a/src/app/main.py +++ b/src/app/main.py @@ -2,6 +2,7 @@ Main module of the python package. """ + def main(): """Main method called from from the command line.""" print("Hello, world") From e955c12dfdd5cb60bd4de3c2de7a953a0bd5158e Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 20 Apr 2025 12:01:12 +0200 Subject: [PATCH 24/59] Removed docs stage from ci --- .github/workflows/ci.yml | 26 -------------------------- 1 file changed, 26 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 90b2063..3f2833e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -114,29 +114,3 @@ jobs: run: | pip install pylint pylint src/ - docs: - runs-on: ubuntu-latest - - steps: - # Checkout the repository - - name: Checkout code - uses: actions/checkout@v3 - - # Set up Python - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: '3.10' # Adjust as needed - - # Cache pip dependencies - - name: Cache pip - uses: actions/cache@v3 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }} - restore-keys: | - ${{ runner.os }}-pip- - - - name: Test docs build - run: | - pip install ".[docs]" From 2d65610a50852d1719e225c16d882394e06400f6 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 20 Apr 2025 12:16:33 +0200 Subject: [PATCH 25/59] Create jekyll-gh-pages.yml --- .github/workflows/jekyll-gh-pages.yml | 51 +++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 .github/workflows/jekyll-gh-pages.yml diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml new file mode 100644 index 0000000..4b8bc4f --- /dev/null +++ b/.github/workflows/jekyll-gh-pages.yml @@ -0,0 +1,51 @@ +# Sample workflow for building and deploying a Jekyll site to GitHub Pages +name: Deploy Jekyll with GitHub Pages dependencies preinstalled + +on: + # Runs on pushes targeting the default branch + push: + branches: ["devel"] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Build with Jekyll + uses: actions/jekyll-build-pages@v1 + with: + source: ./ + destination: ./_site + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 From cbeed7182599d3826ec7a5400b3dac20664cdad7 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 20 Apr 2025 12:21:26 +0200 Subject: [PATCH 26/59] Set paths --- .github/workflows/jekyll-gh-pages.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml index 4b8bc4f..67b54ae 100644 --- a/.github/workflows/jekyll-gh-pages.yml +++ b/.github/workflows/jekyll-gh-pages.yml @@ -33,8 +33,8 @@ jobs: - name: Build with Jekyll uses: actions/jekyll-build-pages@v1 with: - source: ./ - destination: ./_site + source: docs/ + destination: docs/_site - name: Upload artifact uses: actions/upload-pages-artifact@v3 From c0df1bb59bdb35c773b2b309fbec7a74a1de7423 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 20 Apr 2025 16:02:43 +0200 Subject: [PATCH 27/59] docs testsing --- .github/workflows/jekyll-gh-pages.yml | 13 +++++++++++++ README.md | 13 +++++++++++++ 2 files changed, 26 insertions(+) diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml index 67b54ae..150ae76 100644 --- a/.github/workflows/jekyll-gh-pages.yml +++ b/.github/workflows/jekyll-gh-pages.yml @@ -5,6 +5,10 @@ on: # Runs on pushes targeting the default branch push: branches: ["devel"] + pull_request: + branches: + - main + - devel # Allows you to run this workflow manually from the Actions tab workflow_dispatch: @@ -30,6 +34,15 @@ jobs: uses: actions/checkout@v4 - name: Setup Pages uses: actions/configure-pages@v5 + - name: Install dependencies + run: | + pip install ".[docs]" + - name: Sphinx build + run: | + sphinx-apidoc -o docs/ src/app/ + cd docs/ + make clean + make html - name: Build with Jekyll uses: actions/jekyll-build-pages@v1 with: diff --git a/README.md b/README.md index 43221df..4e7a699 100644 --- a/README.md +++ b/README.md @@ -21,4 +21,17 @@ Run the code with ``` template-python +``` + +# Build docs + + +``` +# https://medium.com/@pratikdomadiya123/build-project-documentation-quickly-with-the-sphinx-python-2a9732b66594 +sphinx-apidoc -o docs/ src/app/ +cd docs/ +make clean +make html +cd ../ +open docs/_build/html/index.html ``` \ No newline at end of file From 58561ba366d3d7c23d22b13a6cfd700bb45db890 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:05:47 +0200 Subject: [PATCH 28/59] Cleaned up testing --- .github/workflows/ci.yml | 116 ---------------------------------- .github/workflows/testing.yml | 61 ++++++++++++++++++ 2 files changed, 61 insertions(+), 116 deletions(-) delete mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/testing.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml deleted file mode 100644 index 3f2833e..0000000 --- a/.github/workflows/ci.yml +++ /dev/null @@ -1,116 +0,0 @@ -name: CI - -on: - push: - branches: - - main - - devel - pull_request: - branches: - - main - - devel - -jobs: - build: - runs-on: ubuntu-latest - - steps: - # Checkout the repository - - name: Checkout code - uses: actions/checkout@v3 - - # Set up Python - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: '3.10' # Adjust as needed - - # Cache pip dependencies - - name: Cache pip - uses: actions/cache@v3 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }} - restore-keys: | - ${{ runner.os }}-pip- - - # Create virtual environment and install project from pyproject.toml - - name: Set up virtual environment and install project - run: | - python -m venv env - source env/bin/activate - pip install --upgrade pip - pip install ".[test]" - - # Run a basic command to check installation - - name: Check installation - run: | - source env/bin/activate - template-python - - # Run tests - - name: Run tests - run: | - source env/bin/activate - pytest . - env: - CI: true - - - name: Test docs build - run: | - pip install ".[docs]" - sphinx-apidoc -o docs src/app - cd docs - make clean - make html - cd .. - ls docs/_build/html/index.html - - # Static analysis - static-analysis: - runs-on: ubuntu-latest - steps: - - name: Checkout the code - uses: actions/checkout@v4 - - - name: Download and run cloc - run: | - curl -s https://raw.githubusercontent.com/AlDanial/cloc/master/cloc > cloc - chmod +x cloc - ./cloc --version - ./cloc $(git ls-files) - - - name: Code formatting with black - run: | - pip install black - pip install "black[jupyter]" - black --check src/ - - - name: Code formatting with isort - run: | - pip install isort - isort --check src/ - - - name: Code formatting with prospector - continue-on-error: true - run: | - pip install mypy - mypy src/ - - - name: Code formatting with prospector - continue-on-error: true - run: | - pip install prospector - prospector src/ - - - name: Code formatting with ruff - continue-on-error: true - run: | - pip install ruff - ruff check src/ - - - name: Code formatting with pylint - continue-on-error: true - run: | - pip install pylint - pylint src/ diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml new file mode 100644 index 0000000..fe24a48 --- /dev/null +++ b/.github/workflows/testing.yml @@ -0,0 +1,61 @@ +name: Tests + +on: + push: + branches: + - main + - devel + pull_request: + branches: + - main + - devel + +jobs: + build: + runs-on: ubuntu-latest + + steps: + # Checkout the repository + - name: Checkout code + uses: actions/checkout@v3 + + # Set up Python + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' # Adjust as needed + + # Cache pip dependencies + - name: Cache pip + uses: actions/cache@v3 + with: + path: ~/.cache/pip + key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }} + restore-keys: | + ${{ runner.os }}-pip- + + - name: Install project + run: | + pip install --upgrade pip + pip install ".[test]" + + - name: Check installation + run: | + template-python + + - name: Run tests + run: | + pytest . + + - name: Test tutorials + run: | + jupyter nbconvert --to notebook --execute tutorials/*.ipynb --output-dir=/tmp --ExecutePreprocessor.timeout=300 + + - name: Test docs build + run: | + pip install ".[docs]" + cd docs + make clean + make html + cd .. + ls docs/_build/html/index.html \ No newline at end of file From 07ce7f062d0636684af7ce022fc27eed24f096dd Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:05:56 +0200 Subject: [PATCH 29/59] Moved static analysis to .github/workflows/static_analysis.yml --- .github/workflows/static_analysis.yml | 64 +++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 .github/workflows/static_analysis.yml diff --git a/.github/workflows/static_analysis.yml b/.github/workflows/static_analysis.yml new file mode 100644 index 0000000..aa16191 --- /dev/null +++ b/.github/workflows/static_analysis.yml @@ -0,0 +1,64 @@ +name: Static analysis + +on: + push: + branches: + - main + - devel + pull_request: + branches: + - main + - devel + +jobs: + static-analysis: + runs-on: ubuntu-latest + steps: + - name: Checkout the code + uses: actions/checkout@v4 + + - name: Download and run cloc + run: | + curl -s https://raw.githubusercontent.com/AlDanial/cloc/master/cloc > cloc + chmod +x cloc + ./cloc --version + ./cloc $(git ls-files) + + - name: Code formatting with black + continue-on-error: true + run: | + pip install black + pip install "black[jupyter]" + black --check src/ + black --check tutorials/ + + - name: Code formatting with isort + continue-on-error: true + run: | + pip install isort + isort --check src/ + isort --check tutorials/ + + - name: Code formatting with prospector + continue-on-error: true + run: | + pip install mypy + mypy src/ + + - name: Code formatting with prospector + continue-on-error: true + run: | + pip install prospector + prospector src/ + + - name: Code formatting with ruff + continue-on-error: true + run: | + pip install ruff + ruff check src/ + + - name: Code formatting with pylint + continue-on-error: true + run: | + pip install pylint + pylint src/ From 8d2e8ff1c4f5951f6efea730df63ec0a8ee9cf81 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:06:58 +0200 Subject: [PATCH 30/59] Added docs workflow --- .github/workflows/docs.yml | 62 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..a24004d --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,62 @@ +name: Deploy docs to GitHub Pages + +# on: +# push: +# branches: ["devel", "main"] # TODO: Set to main only after release +# workflow_dispatch: +on: + push: + branches: + - main + - devel + pull_request: + branches: + - main + - devel + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install pandoc + run: | + sudo apt-get update + sudo apt-get install -y pandoc + + - name: Install Python dependencies + run: | + python -m pip install --upgrade pip + pip install ".[docs]" + + - name: Build Sphinx docs + run: | + cd docs + make html + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Upload built docs + uses: actions/upload-pages-artifact@v3 + with: + path: docs/build/html/ + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 From dcc64fe70fb943956e79bc8801a12a16e6a303a3 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:10:56 +0200 Subject: [PATCH 31/59] Added .pre-commit-config.yaml --- .pre-commit-config.yaml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 .pre-commit-config.yaml diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..af67085 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,15 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 # Use the latest stable version + hooks: + - id: check-added-large-files # Prevent giant files from being committed. + args: ["--maxkb=1000"] + - id: check-merge-conflict # Check for files that contain merge conflict strings. + - id: check-toml # Attempts to load all TOML files to verify syntax. + - id: check-yaml # Attempts to load all yaml files to verify syntax. + args: ["--unsafe"] + + - repo: https://github.com/kynan/nbstripout + rev: 0.8.1 + hooks: + - id: nbstripout # remove jupyter notebook cell output From 0b41400b3efdfae323091258b4e469a894059515 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:12:27 +0200 Subject: [PATCH 32/59] Added deps --- pyproject.toml | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index b7bfce9..d87e33b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,15 +21,22 @@ dependencies = [ [project.optional-dependencies] test = ["pytest", "coverage"] dev = [ - "template-python[test]", + "template-python[test,docs]", "black", "isort", "ruff", ] + # https://medium.com/@pratikdomadiya123/build-project-documentation-quickly-with-the-sphinx-python-2a9732b66594 docs = [ + "myst-parser", "sphinx", - "sphinx_rtd_theme", + "sphinx-rtd-theme", + "nbsphinx", + "ipykernel", + "nbconvert", + "pre-commit", + "pyproject-fmt", ] [project.urls] From 6147869a1030dffd72c898ac1c99b6474456bc18 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:12:51 +0200 Subject: [PATCH 33/59] Formatted pyproject.toml with pyproject-fmt --- pyproject.toml | 62 ++++++++++++++++++++++++++------------------------ 1 file changed, 32 insertions(+), 30 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index d87e33b..8fd2526 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,49 +1,51 @@ [build-system] -requires = ["setuptools", "wheel"] build-backend = "setuptools.build_meta" +requires = [ "setuptools", "wheel" ] + [project] name = "template-python" version = "0.1" description = "Template python repository." readme = "README.md" +keywords = [ "python" ] +license = { file = "LICENSE.txt" } +authors = [ { name = "Max" } ] requires-python = ">=3.8" -license = {file = "LICENSE.txt"} -keywords = ["python"] -authors = [{name = "Max"}] classifiers = [ - "Development Status :: 3 - Alpha", + "Development Status :: 3 - Alpha", + "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", ] dependencies = [ - "numpy", + "numpy", ] -[project.optional-dependencies] -test = ["pytest", "coverage"] -dev = [ - "template-python[test,docs]", - "black", - "isort", - "ruff", +optional-dependencies.dev = [ + "black", + "isort", + "ruff", + "template-python[test,docs]", ] - # https://medium.com/@pratikdomadiya123/build-project-documentation-quickly-with-the-sphinx-python-2a9732b66594 -docs = [ - "myst-parser", - "sphinx", - "sphinx-rtd-theme", - "nbsphinx", - "ipykernel", - "nbconvert", - "pre-commit", - "pyproject-fmt", +optional-dependencies.docs = [ + "ipykernel", + "myst-parser", + "nbconvert", + "nbsphinx", + "pre-commit", + "pyproject-fmt", + "sphinx", + "sphinx-rtd-theme", ] - -[project.urls] -"Source" = "https://github.com/max-models/template-python" +optional-dependencies.test = [ "coverage", "pytest" ] +urls."Source" = "https://github.com/max-models/template-python" +scripts.template-python = "app.main:main" [tool.setuptools.packages.find] -where = ["src"] - -[project.scripts] -template-python = "app.main:main" +where = [ "src" ] From 6d29a0588902c9e0f9908b1550622fff97c0d764 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:13:05 +0200 Subject: [PATCH 34/59] Added tutorial --- tutorials/tutorial_01.ipynb | 51 +++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 tutorials/tutorial_01.ipynb diff --git a/tutorials/tutorial_01.ipynb b/tutorials/tutorial_01.ipynb new file mode 100644 index 0000000..e253436 --- /dev/null +++ b/tutorials/tutorial_01.ipynb @@ -0,0 +1,51 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "efb79425-958b-412c-afa9-055e27a69baa", + "metadata": {}, + "source": [ + "# Tutorial 1" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "68ad1562-4953-444c-96c7-9026bcc54cc7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Example tutorial which will be published in the docs!\n" + ] + } + ], + "source": [ + "print('Example tutorial which will be published in the docs!')" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.13.3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} From c8d5039e86837c4fb8614ef328b7771deaf05896 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:14:14 +0200 Subject: [PATCH 35/59] Removed .github/workflows/jekyll-gh-pages.yml --- .github/workflows/jekyll-gh-pages.yml | 64 --------------------------- 1 file changed, 64 deletions(-) delete mode 100644 .github/workflows/jekyll-gh-pages.yml diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml deleted file mode 100644 index 150ae76..0000000 --- a/.github/workflows/jekyll-gh-pages.yml +++ /dev/null @@ -1,64 +0,0 @@ -# Sample workflow for building and deploying a Jekyll site to GitHub Pages -name: Deploy Jekyll with GitHub Pages dependencies preinstalled - -on: - # Runs on pushes targeting the default branch - push: - branches: ["devel"] - pull_request: - branches: - - main - - devel - - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write - -# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. -# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. -concurrency: - group: "pages" - cancel-in-progress: false - -jobs: - # Build job - build: - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Setup Pages - uses: actions/configure-pages@v5 - - name: Install dependencies - run: | - pip install ".[docs]" - - name: Sphinx build - run: | - sphinx-apidoc -o docs/ src/app/ - cd docs/ - make clean - make html - - name: Build with Jekyll - uses: actions/jekyll-build-pages@v1 - with: - source: docs/ - destination: docs/_site - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - - # Deployment job - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - needs: build - steps: - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 From 6ed5c5447e5632b5c98b538e7974d4a98119be7b Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:16:29 +0200 Subject: [PATCH 36/59] Install with dev in the ci --- .github/workflows/testing.yml | 2 +- pyproject.toml | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml index fe24a48..b713ea5 100644 --- a/.github/workflows/testing.yml +++ b/.github/workflows/testing.yml @@ -37,7 +37,7 @@ jobs: - name: Install project run: | pip install --upgrade pip - pip install ".[test]" + pip install ".[dev]" - name: Check installation run: | diff --git a/pyproject.toml b/pyproject.toml index 8fd2526..c870991 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,6 +38,7 @@ optional-dependencies.docs = [ "myst-parser", "nbconvert", "nbsphinx", + "jupyterlab", "pre-commit", "pyproject-fmt", "sphinx", From bebacc8ea71f74c03d0e9349bc55de5cb86bd53f Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:18:39 +0200 Subject: [PATCH 37/59] build --> _build --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a24004d..961d762 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -55,7 +55,7 @@ jobs: - name: Upload built docs uses: actions/upload-pages-artifact@v3 with: - path: docs/build/html/ + path: docs/_build/html/ - name: Deploy to GitHub Pages id: deployment From 6e11d01c5513963e3c35027926c83099652d13fc Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:19:52 +0200 Subject: [PATCH 38/59] build tutorial in ci --- docs/conf.py | 19 ++++++++++++++++++- docs/index.rst | 4 +++- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 0c2f42c..920635b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -4,6 +4,23 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html import os import sys +import shutil + + +def copy_tutorials(app): + src = os.path.abspath("../tutorials") + dst = os.path.abspath("source/tutorials") + + # Remove existing target directory if it exists + if os.path.exists(dst): + shutil.rmtree(dst) + + shutil.copytree(src, dst) + + +def setup(app): + app.connect("builder-inited", copy_tutorials) + # sys.path.insert(0, os.path.abspath('..')) sys.path.insert(0, os.path.abspath("../src/app")) @@ -51,4 +68,4 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] \ No newline at end of file +html_static_path = ["_static"] diff --git a/docs/index.rst b/docs/index.rst index e354a7c..439c8d8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,5 +13,7 @@ documentation for details. .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Tutorials: + + tutorials/tutorial_01 From 8c6eea8d86e790e9e193546eaf99ecd24ee526e6 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:21:16 +0200 Subject: [PATCH 39/59] Don't allow failure of black and isort --- .github/workflows/static_analysis.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/static_analysis.yml b/.github/workflows/static_analysis.yml index aa16191..e6282db 100644 --- a/.github/workflows/static_analysis.yml +++ b/.github/workflows/static_analysis.yml @@ -25,7 +25,6 @@ jobs: ./cloc $(git ls-files) - name: Code formatting with black - continue-on-error: true run: | pip install black pip install "black[jupyter]" @@ -33,7 +32,6 @@ jobs: black --check tutorials/ - name: Code formatting with isort - continue-on-error: true run: | pip install isort isort --check src/ From 480d8d1c4b08f0d161e6c53f3101a06c970ebf0b Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:28:55 +0200 Subject: [PATCH 40/59] Install black[jupyter] and format tutorial --- pyproject.toml | 2 +- tutorials/tutorial_01.ipynb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index c870991..e8e824f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,7 +27,7 @@ dependencies = [ ] optional-dependencies.dev = [ - "black", + "black[jupyter]", "isort", "ruff", "template-python[test,docs]", diff --git a/tutorials/tutorial_01.ipynb b/tutorials/tutorial_01.ipynb index e253436..4f568bb 100644 --- a/tutorials/tutorial_01.ipynb +++ b/tutorials/tutorial_01.ipynb @@ -23,7 +23,7 @@ } ], "source": [ - "print('Example tutorial which will be published in the docs!')" + "print(\"Example tutorial which will be published in the docs!\")" ] } ], From e362b660e0efdea47e9bd3d0893bd9804968183d Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:31:01 +0200 Subject: [PATCH 41/59] removed docs --- docs/Makefile | 20 -------------- docs/conf.py | 71 ------------------------------------------------ docs/index.rst | 19 ------------- docs/main.rst | 7 ----- docs/make.bat | 35 ------------------------ docs/modules.rst | 7 ----- 6 files changed, 159 deletions(-) delete mode 100644 docs/Makefile delete mode 100644 docs/conf.py delete mode 100644 docs/index.rst delete mode 100644 docs/main.rst delete mode 100644 docs/make.bat delete mode 100644 docs/modules.rst diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d4bb2cb..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 920635b..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,71 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html -import os -import sys -import shutil - - -def copy_tutorials(app): - src = os.path.abspath("../tutorials") - dst = os.path.abspath("source/tutorials") - - # Remove existing target directory if it exists - if os.path.exists(dst): - shutil.rmtree(dst) - - shutil.copytree(src, dst) - - -def setup(app): - app.connect("builder-inited", copy_tutorials) - - -# sys.path.insert(0, os.path.abspath('..')) -sys.path.insert(0, os.path.abspath("../src/app")) - - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -project = "python-template" -copyright = "2025, Max" -author = "Max" - -# The full version, including alpha/beta/rc tags -release = "1.0.0" - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.viewcode", - "sphinx.ext.napoleon", - # 'myst_parser', -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "sphinx_rtd_theme" - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 439c8d8..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. python-template documentation master file, created by - sphinx-quickstart on Sun Apr 20 11:40:45 2025. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -python-template documentation -============================= - -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. - - -.. toctree:: - :maxdepth: 2 - :caption: Tutorials: - - tutorials/tutorial_01 - diff --git a/docs/main.rst b/docs/main.rst deleted file mode 100644 index 7874bd9..0000000 --- a/docs/main.rst +++ /dev/null @@ -1,7 +0,0 @@ -main module -=========== - -.. automodule:: main - :members: - :show-inheritance: - :undoc-members: diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 32bb245..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/modules.rst b/docs/modules.rst deleted file mode 100644 index 6378a90..0000000 --- a/docs/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -app -=== - -.. toctree:: - :maxdepth: 4 - - main From 37dc5fd90288bbf9c9f36f919ee78609e5bb63bb Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:33:58 +0200 Subject: [PATCH 42/59] Updated docs --- docs/Makefile | 20 ++++++++++ docs/make.bat | 35 +++++++++++++++++ docs/source/conf.py | 49 ++++++++++++++++++++++++ docs/source/index.rst | 18 +++++++++ docs/source/tutorials/tutorial_01.ipynb | 51 +++++++++++++++++++++++++ 5 files changed, 173 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/tutorials/tutorial_01.ipynb diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..9c91e46 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,49 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import os +import shutil + + +def copy_tutorials(app): + src = os.path.abspath("../tutorials") + dst = os.path.abspath("source/tutorials") + + # Remove existing target directory if it exists + if os.path.exists(dst): + shutil.rmtree(dst) + + shutil.copytree(src, dst) + + +def setup(app): + app.connect("builder-inited", copy_tutorials) + + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "python-template" +copyright = "2025, Max Lindqvist" +author = "Max Lindqvist" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "nbsphinx", + "sphinx.ext.mathjax", + "sphinx.ext.autodoc", +] + +templates_path = ["_templates"] +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_rtd_theme" +html_static_path = ["_static"] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..eb4a964 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,18 @@ +.. Documentation master file, created by + sphinx-quickstart on Sun Jun 22 11:14:00 2025. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +python-template documentation +======================== + +Add your content using ``reStructuredText`` syntax. See the +`reStructuredText `_ +documentation for details. + + +.. toctree:: + :maxdepth: 2 + :caption: Tutorials: + + tutorials/tutorial_01 diff --git a/docs/source/tutorials/tutorial_01.ipynb b/docs/source/tutorials/tutorial_01.ipynb new file mode 100644 index 0000000..4f568bb --- /dev/null +++ b/docs/source/tutorials/tutorial_01.ipynb @@ -0,0 +1,51 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "efb79425-958b-412c-afa9-055e27a69baa", + "metadata": {}, + "source": [ + "# Tutorial 1" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "68ad1562-4953-444c-96c7-9026bcc54cc7", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Example tutorial which will be published in the docs!\n" + ] + } + ], + "source": [ + "print(\"Example tutorial which will be published in the docs!\")" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.13.3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} From 6ea58a5cbc9e73852795fed3de7c1a742869b73c Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:34:31 +0200 Subject: [PATCH 43/59] elongated underline --- docs/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index eb4a964..fedda8e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,7 +4,7 @@ contain the root `toctree` directive. python-template documentation -======================== +============================= Add your content using ``reStructuredText`` syntax. See the `reStructuredText `_ From c87769ae0da35cbac193982df4e5cfc21d6f72c2 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:40:40 +0200 Subject: [PATCH 44/59] Added pandoc to docs --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index e8e824f..13bb827 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -39,6 +39,7 @@ optional-dependencies.docs = [ "nbconvert", "nbsphinx", "jupyterlab", + "pandoc", "pre-commit", "pyproject-fmt", "sphinx", From fb3163272c067f43cca6a9e0f15c0cb2b226c04a Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:45:54 +0200 Subject: [PATCH 45/59] Install pandoc with apt-get --- .github/workflows/testing.yml | 5 +++++ pyproject.toml | 1 - 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml index b713ea5..79ef452 100644 --- a/.github/workflows/testing.yml +++ b/.github/workflows/testing.yml @@ -34,6 +34,11 @@ jobs: restore-keys: | ${{ runner.os }}-pip- + - name: Install dependencies + run: | + sudo apt-get update + sudo apt-get install -y pandoc + - name: Install project run: | pip install --upgrade pip diff --git a/pyproject.toml b/pyproject.toml index 13bb827..e8e824f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -39,7 +39,6 @@ optional-dependencies.docs = [ "nbconvert", "nbsphinx", "jupyterlab", - "pandoc", "pre-commit", "pyproject-fmt", "sphinx", From 2f333a41b378e079e077ecb77791498575623914 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:48:31 +0200 Subject: [PATCH 46/59] _build --> build --- .github/workflows/docs.yml | 2 +- .github/workflows/testing.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 961d762..a24004d 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -55,7 +55,7 @@ jobs: - name: Upload built docs uses: actions/upload-pages-artifact@v3 with: - path: docs/_build/html/ + path: docs/build/html/ - name: Deploy to GitHub Pages id: deployment diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml index 79ef452..f84e48c 100644 --- a/.github/workflows/testing.yml +++ b/.github/workflows/testing.yml @@ -63,4 +63,4 @@ jobs: make clean make html cd .. - ls docs/_build/html/index.html \ No newline at end of file + ls docs/build/html/index.html \ No newline at end of file From 7db4b8a958a2531526015324a295109003564fdf Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 16:54:50 +0200 Subject: [PATCH 47/59] Added link to documentation --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4e7a699..92c44e9 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,9 @@ # template-python + Template repository for python projects +Documentation: https://max-models.github.io/template-python/ + # Install Create and activate python environment @@ -34,4 +37,4 @@ make clean make html cd ../ open docs/_build/html/index.html -``` \ No newline at end of file +``` From dccc029ed4989ff4530bff37e8e5523e49bab6fe Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 22 Jun 2025 17:05:46 +0200 Subject: [PATCH 48/59] Only build docs on push to devel/main (#5) * Only build docs on push to devel/main * Renames to mypy (mistake) --- .github/workflows/docs.yml | 13 ++----------- .github/workflows/static_analysis.yml | 2 +- 2 files changed, 3 insertions(+), 12 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a24004d..c59b8ea 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,18 +1,9 @@ name: Deploy docs to GitHub Pages -# on: -# push: -# branches: ["devel", "main"] # TODO: Set to main only after release -# workflow_dispatch: on: push: - branches: - - main - - devel - pull_request: - branches: - - main - - devel + branches: ["devel", "main"] # TODO: Set to main only after release + workflow_dispatch: permissions: contents: read diff --git a/.github/workflows/static_analysis.yml b/.github/workflows/static_analysis.yml index e6282db..bf3f9b6 100644 --- a/.github/workflows/static_analysis.yml +++ b/.github/workflows/static_analysis.yml @@ -37,7 +37,7 @@ jobs: isort --check src/ isort --check tutorials/ - - name: Code formatting with prospector + - name: Code formatting with mypy continue-on-error: true run: | pip install mypy From 89d3f0d6e600319c085e4831720078cf20938442 Mon Sep 17 00:00:00 2001 From: Max Date: Sat, 13 Sep 2025 19:29:32 +0200 Subject: [PATCH 49/59] Split the linting in the CI into multiple jobs (#6) * Reference tutorials with glob instead of specific paths * Split each linter into it's own job --- .github/workflows/static_analysis.yml | 63 ++++++++++++++++++++++----- docs/source/index.rst | 3 +- 2 files changed, 53 insertions(+), 13 deletions(-) diff --git a/.github/workflows/static_analysis.yml b/.github/workflows/static_analysis.yml index bf3f9b6..2fba12b 100644 --- a/.github/workflows/static_analysis.yml +++ b/.github/workflows/static_analysis.yml @@ -10,8 +10,12 @@ on: - main - devel +defaults: + run: + shell: bash + jobs: - static-analysis: + cloc: runs-on: ubuntu-latest steps: - name: Checkout the code @@ -24,39 +28,74 @@ jobs: ./cloc --version ./cloc $(git ls-files) + black: + runs-on: ubuntu-latest + steps: + - name: Checkout the code + uses: actions/checkout@v4 + - name: Code formatting with black run: | - pip install black - pip install "black[jupyter]" + pip install black "black[jupyter]" black --check src/ black --check tutorials/ + isort: + runs-on: ubuntu-latest + steps: + - name: Checkout the code + uses: actions/checkout@v4 + - name: Code formatting with isort run: | pip install isort isort --check src/ isort --check tutorials/ - - name: Code formatting with mypy - continue-on-error: true + mypy: + runs-on: ubuntu-latest + continue-on-error: true + steps: + - name: Checkout the code + uses: actions/checkout@v4 + + - name: Type checking with mypy run: | pip install mypy mypy src/ - - name: Code formatting with prospector - continue-on-error: true + prospector: + runs-on: ubuntu-latest + continue-on-error: true + steps: + - name: Checkout the code + uses: actions/checkout@v4 + + - name: Code analysis with prospector run: | pip install prospector prospector src/ - - - name: Code formatting with ruff - continue-on-error: true + + ruff: + runs-on: ubuntu-latest + continue-on-error: true + steps: + - name: Checkout the code + uses: actions/checkout@v4 + + - name: Linting with ruff run: | pip install ruff ruff check src/ - - name: Code formatting with pylint - continue-on-error: true + pylint: + runs-on: ubuntu-latest + continue-on-error: true + steps: + - name: Checkout the code + uses: actions/checkout@v4 + + - name: Linting with pylint run: | pip install pylint pylint src/ diff --git a/docs/source/index.rst b/docs/source/index.rst index fedda8e..df6c5b3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,5 +14,6 @@ documentation for details. .. toctree:: :maxdepth: 2 :caption: Tutorials: + :glob: - tutorials/tutorial_01 + tutorials/* \ No newline at end of file From 78f5e47ac6a0874f96ecd94bf92cf5a3b4f47666 Mon Sep 17 00:00:00 2001 From: Max Date: Sat, 13 Sep 2025 19:45:48 +0200 Subject: [PATCH 50/59] Added || true to mypy, prospector, pylint, and ruff (#7) * Reference tutorials with glob instead of specific paths * Split each linter into it's own job * Added || true --- .github/workflows/static_analysis.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/static_analysis.yml b/.github/workflows/static_analysis.yml index 2fba12b..61b3cb6 100644 --- a/.github/workflows/static_analysis.yml +++ b/.github/workflows/static_analysis.yml @@ -62,7 +62,7 @@ jobs: - name: Type checking with mypy run: | pip install mypy - mypy src/ + mypy src/ || true prospector: runs-on: ubuntu-latest @@ -74,7 +74,7 @@ jobs: - name: Code analysis with prospector run: | pip install prospector - prospector src/ + prospector src/ || true ruff: runs-on: ubuntu-latest @@ -86,7 +86,7 @@ jobs: - name: Linting with ruff run: | pip install ruff - ruff check src/ + ruff check src/ || true pylint: runs-on: ubuntu-latest @@ -98,4 +98,4 @@ jobs: - name: Linting with pylint run: | pip install pylint - pylint src/ + pylint src/ || true From 7d3ae792ff041afd43041b2d6c9b8aff70a7c49a Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 10:18:24 +0200 Subject: [PATCH 51/59] Change sphinx theme (#8) * Moved tutorials * Updated conf and wrote docs in markdown * Updated gitignore * Updated instructions * Removed sidebar * Updated navbar color * Removed caption * Added sphinx_bootstrap_theme to deps --- .gitignore | 1 + README.md | 4 - docs/source/api.md | 6 + docs/source/conf.py | 111 +++++++++++++++++- docs/source/index.md | 11 ++ docs/source/index.rst | 19 --- docs/source/quickstart.md | 38 ++++++ docs/source/tutorials.md | 9 ++ pyproject.toml | 1 + .../example_tutorial.ipynb | 0 tutorials/tutorial_01.ipynb | 51 -------- 11 files changed, 172 insertions(+), 79 deletions(-) create mode 100644 docs/source/api.md create mode 100644 docs/source/index.md delete mode 100644 docs/source/index.rst create mode 100644 docs/source/quickstart.md create mode 100644 docs/source/tutorials.md rename docs/source/tutorials/tutorial_01.ipynb => tutorials/example_tutorial.ipynb (100%) delete mode 100644 tutorials/tutorial_01.ipynb diff --git a/.gitignore b/.gitignore index 99ffb91..eaf73dd 100644 --- a/.gitignore +++ b/.gitignore @@ -71,6 +71,7 @@ instance/ # Sphinx documentation docs/_build/ +docs/source/tutorials/ # PyBuilder .pybuilder/ diff --git a/README.md b/README.md index 92c44e9..8ca65e2 100644 --- a/README.md +++ b/README.md @@ -30,10 +30,6 @@ template-python ``` -# https://medium.com/@pratikdomadiya123/build-project-documentation-quickly-with-the-sphinx-python-2a9732b66594 -sphinx-apidoc -o docs/ src/app/ -cd docs/ -make clean make html cd ../ open docs/_build/html/index.html diff --git a/docs/source/api.md b/docs/source/api.md new file mode 100644 index 0000000..a1c08b6 --- /dev/null +++ b/docs/source/api.md @@ -0,0 +1,6 @@ +# API + +Description of the API + +```{toctree} +:maxdepth: 1 \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 9c91e46..4b57f55 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -5,7 +5,8 @@ import os import shutil - +# At the top. +import sphinx_bootstrap_theme def copy_tutorials(app): src = os.path.abspath("../tutorials") @@ -20,14 +21,16 @@ def copy_tutorials(app): def setup(app): app.connect("builder-inited", copy_tutorials) + # app.add_stylesheet("my-styles.css") + app.add_css_file("custom.css") # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = "python-template" -copyright = "2025, Max Lindqvist" -author = "Max Lindqvist" +copyright = "2025, Max" +author = "Max" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -36,14 +39,112 @@ def setup(app): "nbsphinx", "sphinx.ext.mathjax", "sphinx.ext.autodoc", + "myst_parser", # enable Markdown support ] -templates_path = ["_templates"] exclude_patterns = [] +# Recognize both .rst and .md +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = "sphinx_rtd_theme" +# html_theme = "furo" +# conf.py +# ... + +# Activate the theme. +html_theme = 'bootstrap' +html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() + +# (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24). +# Path should be relative to the ``_static`` files directory. +# html_logo = "my_logo.png" + +# Theme options are theme-specific and customize the look and feel of a +# theme further. +html_theme_options = { + # Navigation bar title. (Default: ``project`` value) + 'navbar_title': "python-template", + + # Tab name for entire site. (Default: "Site") + + 'navbar_site_name': "Site", + + # A list of tuples containing pages or urls to link to. + # Valid tuples should be in the following forms: + # (name, page) # a link to a page + # (name, "/aa/bb", 1) # a link to an arbitrary relative url + # (name, "http://example.com", True) # arbitrary absolute url + # Note the "1" or "True" value above as the third argument to indicate + # an arbitrary url. + 'navbar_links': [ + ("Quickstart", "quickstart"), + ("Tutorials", "tutorial"), + ("API", "api"), + # ("Link", "http://example.com", True), + ], + + # Render the next and previous page links in navbar. (Default: true) + 'navbar_sidebarrel': False, + + # Render the current pages TOC in the navbar. (Default: true) + 'navbar_pagenav': False, + + # Tab name for the current pages TOC. (Default: "Page") + 'navbar_pagenav_name': "Page", + + # Global TOC depth for "site" navbar tab. (Default: 1) + # Switching to -1 shows all levels. + 'globaltoc_depth': 2, + + # Include hidden TOCs in Site navbar? + # + # Note: If this is "false", you cannot have mixed ``:hidden:`` and + # non-hidden ``toctree`` directives in the same page, or else the build + # will break. + # + # Values: "true" (default) or "false" + 'globaltoc_includehidden': "true", + + # HTML navbar class (Default: "navbar") to attach to
element. + # For black navbar, do "navbar navbar-inverse" + 'navbar_class': "navbar inverse", + + # Fix navigation bar to top of page? + # Values: "true" (default) or "false" + 'navbar_fixed_top': "true", + + # Location of link to source. + # Options are "nav" (default), "footer" or anything else to exclude. + 'source_link_position': "footer", + + # Bootswatch (http://bootswatch.com/) theme. + # + # Options are nothing (default) or the name of a valid theme + # such as "cosmo" or "sandstone". + # + # The set of valid themes depend on the version of Bootstrap + # that's used (the next config option). + # + # Currently, the supported themes are: + # - Bootstrap 2: https://bootswatch.com/2 + # - Bootstrap 3: https://bootswatch.com/3 + 'bootswatch_theme': "flatly", + + # Choose Bootstrap version. + # Values: "3" (default) or "2" (in quotes) + 'bootstrap_version': "3", +} + html_static_path = ["_static"] +templates_path = ['_templates'] + + +html_sidebars = { + '**': [] +} diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 0000000..d082474 --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,11 @@ +# Welcome + +Write the documentation of your python package here + +```{toctree} +:maxdepth: 2 +:caption: Contents + +quickstart.md +tutorials.md +api.md diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index df6c5b3..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. Documentation master file, created by - sphinx-quickstart on Sun Jun 22 11:14:00 2025. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -python-template documentation -============================= - -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. - - -.. toctree:: - :maxdepth: 2 - :caption: Tutorials: - :glob: - - tutorials/* \ No newline at end of file diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md new file mode 100644 index 0000000..a2d6ec8 --- /dev/null +++ b/docs/source/quickstart.md @@ -0,0 +1,38 @@ +# Quickstart + +Clone the repo + +``` +git clone ... +``` + +Create and activate python environment + +``` +python -m venv env +source env/bin/activate +pip install --upgrade pip +``` + +Install the code and requirements with pip + +``` +pip install -e . +``` + +Run the code with + +``` +template-python +``` + +# Build docs + +``` +make html +cd ../ +open docs/_build/html/index.html +``` + +```{toctree} +:maxdepth: 1 \ No newline at end of file diff --git a/docs/source/tutorials.md b/docs/source/tutorials.md new file mode 100644 index 0000000..84e10de --- /dev/null +++ b/docs/source/tutorials.md @@ -0,0 +1,9 @@ +# Tutorials + +Here are a few tutorials to help you get started. + +```{toctree} +:maxdepth: 1 +:glob: + +tutorials/* \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index e8e824f..15f873c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -43,6 +43,7 @@ optional-dependencies.docs = [ "pyproject-fmt", "sphinx", "sphinx-rtd-theme", + "sphinx_bootstrap_theme", ] optional-dependencies.test = [ "coverage", "pytest" ] urls."Source" = "https://github.com/max-models/template-python" diff --git a/docs/source/tutorials/tutorial_01.ipynb b/tutorials/example_tutorial.ipynb similarity index 100% rename from docs/source/tutorials/tutorial_01.ipynb rename to tutorials/example_tutorial.ipynb diff --git a/tutorials/tutorial_01.ipynb b/tutorials/tutorial_01.ipynb deleted file mode 100644 index 4f568bb..0000000 --- a/tutorials/tutorial_01.ipynb +++ /dev/null @@ -1,51 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "efb79425-958b-412c-afa9-055e27a69baa", - "metadata": {}, - "source": [ - "# Tutorial 1" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "68ad1562-4953-444c-96c7-9026bcc54cc7", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Example tutorial which will be published in the docs!\n" - ] - } - ], - "source": [ - "print(\"Example tutorial which will be published in the docs!\")" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.13.3" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} From 2a06a65326a89690f02ecc279adc92c561abdb26 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 10:31:14 +0200 Subject: [PATCH 52/59] Removed source/index.rst --- docs/source/index.rst | 16 ---------------- 1 file changed, 16 deletions(-) delete mode 100644 docs/source/index.rst diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index f7fbdd2..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. Documentation master file, created by - sphinx-quickstart on Sun Jun 22 11:14:00 2025. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -maxtikzlib -============================= - -Here are a few tutorials to help you get started with `maxtikzlib` - -.. toctree:: - :maxdepth: 2 - :caption: Tutorials: - :glob: - - tutorials/* From a00d458cd26585a147e0a89e86da070fa90b572b Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 10:32:12 +0200 Subject: [PATCH 53/59] formatting and bugfix --- docs/source/conf.py | 51 +++++++++++++++++---------------------------- 1 file changed, 19 insertions(+), 32 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 216fbd4..7e06359 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -5,9 +5,11 @@ import os import shutil + # At the top. import sphinx_bootstrap_theme + def copy_tutorials(app): src = os.path.abspath("../tutorials") dst = os.path.abspath("source/tutorials") @@ -58,7 +60,7 @@ def setup(app): # ... # Activate the theme. -html_theme = 'bootstrap' +html_theme = "bootstrap" html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() # (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24). @@ -69,12 +71,9 @@ def setup(app): # theme further. html_theme_options = { # Navigation bar title. (Default: ``project`` value) - 'navbar_title': "python-template", - + "navbar_title": "python-template", # Tab name for entire site. (Default: "Site") - - 'navbar_site_name': "Site", - + "navbar_site_name": "Site", # A list of tuples containing pages or urls to link to. # Valid tuples should be in the following forms: # (name, page) # a link to a page @@ -82,26 +81,21 @@ def setup(app): # (name, "http://example.com", True) # arbitrary absolute url # Note the "1" or "True" value above as the third argument to indicate # an arbitrary url. - 'navbar_links': [ + "navbar_links": [ ("Quickstart", "quickstart"), - ("Tutorials", "tutorial"), + ("Tutorials", "tutorials"), ("API", "api"), # ("Link", "http://example.com", True), ], - # Render the next and previous page links in navbar. (Default: true) - 'navbar_sidebarrel': False, - + "navbar_sidebarrel": False, # Render the current pages TOC in the navbar. (Default: true) - 'navbar_pagenav': False, - + "navbar_pagenav": False, # Tab name for the current pages TOC. (Default: "Page") - 'navbar_pagenav_name': "Page", - + "navbar_pagenav_name": "Page", # Global TOC depth for "site" navbar tab. (Default: 1) # Switching to -1 shows all levels. - 'globaltoc_depth': 2, - + "globaltoc_depth": 2, # Include hidden TOCs in Site navbar? # # Note: If this is "false", you cannot have mixed ``:hidden:`` and @@ -109,20 +103,16 @@ def setup(app): # will break. # # Values: "true" (default) or "false" - 'globaltoc_includehidden': "true", - + "globaltoc_includehidden": "true", # HTML navbar class (Default: "navbar") to attach to
element. # For black navbar, do "navbar navbar-inverse" - 'navbar_class': "navbar inverse", - + "navbar_class": "navbar inverse", # Fix navigation bar to top of page? # Values: "true" (default) or "false" - 'navbar_fixed_top': "true", - + "navbar_fixed_top": "true", # Location of link to source. # Options are "nav" (default), "footer" or anything else to exclude. - 'source_link_position': "footer", - + "source_link_position": "footer", # Bootswatch (http://bootswatch.com/) theme. # # Options are nothing (default) or the name of a valid theme @@ -134,17 +124,14 @@ def setup(app): # Currently, the supported themes are: # - Bootstrap 2: https://bootswatch.com/2 # - Bootstrap 3: https://bootswatch.com/3 - 'bootswatch_theme': "flatly", - + "bootswatch_theme": "flatly", # Choose Bootstrap version. # Values: "3" (default) or "2" (in quotes) - 'bootstrap_version': "3", + "bootstrap_version": "3", } html_static_path = ["_static"] -templates_path = ['_templates'] +templates_path = ["_templates"] -html_sidebars = { - '**': [] -} +html_sidebars = {"**": []} From b600cb1d0bf533ce5d7978d5db45c6672430237e Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 10:34:54 +0200 Subject: [PATCH 54/59] bugfix --- .github/workflows/testing.yml | 4 ---- docs/source/quickstart.md | 6 ------ 2 files changed, 10 deletions(-) diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml index f84e48c..0c86b54 100644 --- a/.github/workflows/testing.yml +++ b/.github/workflows/testing.yml @@ -44,10 +44,6 @@ jobs: pip install --upgrade pip pip install ".[dev]" - - name: Check installation - run: | - template-python - - name: Run tests run: | pytest . diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md index a2d6ec8..d8e6e56 100644 --- a/docs/source/quickstart.md +++ b/docs/source/quickstart.md @@ -20,12 +20,6 @@ Install the code and requirements with pip pip install -e . ``` -Run the code with - -``` -template-python -``` - # Build docs ``` From 0405cb1a18340b3012807eda6bba697e2c593f43 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 10:39:31 +0200 Subject: [PATCH 55/59] Fixed bug for 2d plots --- src/maxtikzlib/figure.py | 26 ++++++++++++++++---------- tutorials/tutorial_01.ipynb | 4 ++-- tutorials/tutorial_05.ipynb | 4 ++-- 3 files changed, 20 insertions(+), 14 deletions(-) diff --git a/src/maxtikzlib/figure.py b/src/maxtikzlib/figure.py index 0268780..5f8394e 100644 --- a/src/maxtikzlib/figure.py +++ b/src/maxtikzlib/figure.py @@ -18,7 +18,7 @@ class TikzFigure: - def __init__(self, **kwargs): + def __init__(self, ndim=2, **kwargs): """ Initialize the TikzFigure class for creating TikZ figures. @@ -44,6 +44,7 @@ def __init__(self, **kwargs): self.nodes = [] self.paths = [] self.layers = {} + self._ndim = ndim # Counter for unnamed nodes self._node_counter = 0 @@ -369,14 +370,15 @@ def generate_tikz(self): - tikz_script (str): The TikZ script as a string. """ tikz_script = "\\begin{tikzpicture}\n" - tikz_script += "\\begin{axis}[\n" - tikz_script += "view={20}{30},\n" - tikz_script += "axis lines=center,\n" - tikz_script += "xlabel={$x$},\n" - tikz_script += "ylabel={$y$},\n" - tikz_script += "zlabel={$z$},\n" - tikz_script += "grid=major\n" - tikz_script += " ]\n" + if self.ndim == 3: + tikz_script += "\\begin{axis}[\n" + tikz_script += "view={20}{30},\n" + tikz_script += "axis lines=center,\n" + tikz_script += "xlabel={$x$},\n" + tikz_script += "ylabel={$y$},\n" + tikz_script += "zlabel={$z$},\n" + tikz_script += "grid=major\n" + tikz_script += " ]\n" if self._figure_setup: tikz_script += f"[{self._figure_setup}]" @@ -422,7 +424,8 @@ def generate_tikz(self): for layer in ordered_layers: tikz_script += layer.generate_tikz() - tikz_script += "\\end{axis}\n" + if self.ndim == 3: + tikz_script += "\\end{axis}\n" tikz_script += "\\end{tikzpicture}" # Wrap in figure environment if necessary @@ -675,6 +678,9 @@ def plot_matplotlib(self, ax): ax.set_ylim(min(all_y) - padding, max(all_y) + padding) ax.set_aspect("equal", adjustable="datalim") + @property + def ndim(self): + return self._ndim # class TikzFigure3D diff --git a/tutorials/tutorial_01.ipynb b/tutorials/tutorial_01.ipynb index b6aa47f..364980a 100644 --- a/tutorials/tutorial_01.ipynb +++ b/tutorials/tutorial_01.ipynb @@ -234,7 +234,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "env_maxtikzlib", "language": "python", "name": "python3" }, @@ -248,7 +248,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.3" + "version": "3.13.3" } }, "nbformat": 4, diff --git a/tutorials/tutorial_05.ipynb b/tutorials/tutorial_05.ipynb index 8a27335..2758cf7 100644 --- a/tutorials/tutorial_05.ipynb +++ b/tutorials/tutorial_05.ipynb @@ -70,7 +70,7 @@ "zvec = states[:, 2]\n", "\n", "# Plot the lorenz system\n", - "fig = TikzFigure()\n", + "fig = TikzFigure(ndim=3)\n", "options = [\"color=black\", \"thick\"]\n", "\n", "fig.add_plot3d(xvec, yvec, zvec, options=options, layer=0)\n", @@ -117,7 +117,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.12" + "version": "3.13.3" } }, "nbformat": 4, From 3fea189e30a1b5117f5b90009c854d9288483da3 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 10:40:13 +0200 Subject: [PATCH 56/59] Formattign --- src/maxtikzlib/figure.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/maxtikzlib/figure.py b/src/maxtikzlib/figure.py index 5f8394e..5bab24f 100644 --- a/src/maxtikzlib/figure.py +++ b/src/maxtikzlib/figure.py @@ -682,6 +682,7 @@ def plot_matplotlib(self, ax): def ndim(self): return self._ndim + # class TikzFigure3D From a7bf28ae5974f285b90d3f42fdc7e44bfb09615c Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 10:41:37 +0200 Subject: [PATCH 57/59] Removed test_app.py --- tests/unit/test_app.py | 9 --------- 1 file changed, 9 deletions(-) delete mode 100644 tests/unit/test_app.py diff --git a/tests/unit/test_app.py b/tests/unit/test_app.py deleted file mode 100644 index 5e9299e..0000000 --- a/tests/unit/test_app.py +++ /dev/null @@ -1,9 +0,0 @@ -def test_import_app(): - from app.main import main - - print("app imported") - main() - - -if __name__ == "__main__": - test_import_app() From 19d1be9bc17e4fba1280a5d39bda837b52d0857d Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 12:29:32 +0200 Subject: [PATCH 58/59] Removed .github/workflows/testing.yml --- .github/workflows/testing.yml | 62 ----------------------------------- 1 file changed, 62 deletions(-) delete mode 100644 .github/workflows/testing.yml diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml deleted file mode 100644 index 0c86b54..0000000 --- a/.github/workflows/testing.yml +++ /dev/null @@ -1,62 +0,0 @@ -name: Tests - -on: - push: - branches: - - main - - devel - pull_request: - branches: - - main - - devel - -jobs: - build: - runs-on: ubuntu-latest - - steps: - # Checkout the repository - - name: Checkout code - uses: actions/checkout@v3 - - # Set up Python - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: '3.10' # Adjust as needed - - # Cache pip dependencies - - name: Cache pip - uses: actions/cache@v3 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }} - restore-keys: | - ${{ runner.os }}-pip- - - - name: Install dependencies - run: | - sudo apt-get update - sudo apt-get install -y pandoc - - - name: Install project - run: | - pip install --upgrade pip - pip install ".[dev]" - - - name: Run tests - run: | - pytest . - - - name: Test tutorials - run: | - jupyter nbconvert --to notebook --execute tutorials/*.ipynb --output-dir=/tmp --ExecutePreprocessor.timeout=300 - - - name: Test docs build - run: | - pip install ".[docs]" - cd docs - make clean - make html - cd .. - ls docs/build/html/index.html \ No newline at end of file From 7fa296041e8ab4ee8d9e81bc89ae32d3b3cb1aa2 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 12:31:56 +0200 Subject: [PATCH 59/59] Removed tutorials/example_tutorial.ipynb --- tutorials/example_tutorial.ipynb | 51 -------------------------------- 1 file changed, 51 deletions(-) delete mode 100644 tutorials/example_tutorial.ipynb diff --git a/tutorials/example_tutorial.ipynb b/tutorials/example_tutorial.ipynb deleted file mode 100644 index 4f568bb..0000000 --- a/tutorials/example_tutorial.ipynb +++ /dev/null @@ -1,51 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "efb79425-958b-412c-afa9-055e27a69baa", - "metadata": {}, - "source": [ - "# Tutorial 1" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "68ad1562-4953-444c-96c7-9026bcc54cc7", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Example tutorial which will be published in the docs!\n" - ] - } - ], - "source": [ - "print(\"Example tutorial which will be published in the docs!\")" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.13.3" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -}