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/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 diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml deleted file mode 100644 index 4b8bc4f..0000000 --- a/.github/workflows/jekyll-gh-pages.yml +++ /dev/null @@ -1,51 +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"] - - # 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 diff --git a/.github/workflows/static_analysis.yml b/.github/workflows/static_analysis.yml new file mode 100644 index 0000000..e6282db --- /dev/null +++ b/.github/workflows/static_analysis.yml @@ -0,0 +1,62 @@ +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 + run: | + pip install black + pip install "black[jupyter]" + black --check src/ + black --check tutorials/ + + - name: Code formatting with isort + 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/ diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml new file mode 100644 index 0000000..f84e48c --- /dev/null +++ b/.github/workflows/testing.yml @@ -0,0 +1,66 @@ +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: 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 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 diff --git a/README.md b/README.md index 43221df..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 @@ -21,4 +24,17 @@ Run the code with ``` template-python -``` \ No newline at end of file +``` + +# 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 +``` diff --git a/docs/Makefile b/docs/Makefile index d4bb2cb..d0c3cbf 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,8 +5,8 @@ # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build +SOURCEDIR = source +BUILDDIR = build # Put it first so that "make" without argument is like "make help". help: diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 0c2f42c..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,54 +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 - -# 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/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 index 32bb245..747ffb7 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -7,8 +7,8 @@ REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) -set SOURCEDIR=. -set BUILDDIR=_build +set SOURCEDIR=source +set BUILDDIR=build %SPHINXBUILD% >NUL 2>NUL if errorlevel 9009 ( 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 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/index.rst b/docs/source/index.rst similarity index 73% rename from docs/index.rst rename to docs/source/index.rst index e354a7c..fedda8e 100644 --- a/docs/index.rst +++ b/docs/source/index.rst @@ -1,5 +1,5 @@ -.. python-template documentation master file, created by - sphinx-quickstart on Sun Apr 20 11:40:45 2025. +.. 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. @@ -13,5 +13,6 @@ documentation for details. .. toctree:: :maxdepth: 2 - :caption: Contents: + :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 +} diff --git a/pyproject.toml b/pyproject.toml index b7bfce9..e8e824f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,42 +1,52 @@ [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]", - "black", - "isort", - "ruff", +optional-dependencies.dev = [ + "black[jupyter]", + "isort", + "ruff", + "template-python[test,docs]", ] # https://medium.com/@pratikdomadiya123/build-project-documentation-quickly-with-the-sphinx-python-2a9732b66594 -docs = [ - "sphinx", - "sphinx_rtd_theme", +optional-dependencies.docs = [ + "ipykernel", + "myst-parser", + "nbconvert", + "nbsphinx", + "jupyterlab", + "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" ] diff --git a/tutorials/tutorial_01.ipynb b/tutorials/tutorial_01.ipynb new file mode 100644 index 0000000..4f568bb --- /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 +}