From cbeed7182599d3826ec7a5400b3dac20664cdad7 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 20 Apr 2025 12:21:26 +0200 Subject: [PATCH 01/22] 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 02/22] 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 03/22] 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 04/22] 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 05/22] 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 06/22] 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 07/22] 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 08/22] 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 09/22] 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 10/22] 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 11/22] 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 12/22] 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 13/22] 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 14/22] 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 15/22] 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 16/22] 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 17/22] 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 18/22] 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 19/22] 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 20/22] 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 21/22] _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 22/22] 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 +```