From 387c61102c18e552eee40c91855d8a43571f3efe Mon Sep 17 00:00:00 2001 From: Max Date: Fri, 18 Apr 2025 12:18:23 +0200 Subject: [PATCH 1/8] 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 2/8] 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 3/8] 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 4/8] 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 5/8] 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 6/8] 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 7/8] 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 8/8] 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]"