Add example project

Author: 31ch

.devcontainer/Dockerfile

@@ -1,6 +1,8 @@
-FROM mcr.microsoft.com/devcontainers/python:1-3.12-bullseye
+# https://github.com/devcontainers/images/tree/main/src/python
+FROM mcr.microsoft.com/devcontainers/python:1-3.12-bookworm
 
-# Install Debian packages
-# RUN apt-get update && apt-get install -y --no-install-recommends \
-#     XXX \
-#     && apt-get autoremove -y && apt-get clean -y && rm -rf /var/lib/apt/lists/*
+# [Optional] Uncomment this section to install additional packages.
+# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+#    && apt-get -y install --no-install-recommends \
+#    <your-package-list-here> \
+#    && apt-get autoremove -y && apt-get clean -y && rm -rf /var/lib/apt/lists/*

.devcontainer/devcontainer.json

@@ -7,7 +7,7 @@
 	"build": {
         // Path is relative to the devcontainer.json file.
         "dockerfile": "Dockerfile"
-    }
+    },
 
 	// Features to add to the dev container. More info: https://containers.dev/features.
 	// "features": {},
@@ -16,7 +16,7 @@
 	// "forwardPorts": [],
 
 	// Use 'postCreateCommand' to run commands after the container is created.
-	// "postCreateCommand": "pip3 install --user -r requirements.txt",
+	"postCreateCommand": "pipenv install --dev && pipenv run pip install -e ."
 
 	// Configure tool-specific properties.
 	// "customizations": {},

.gitignore

@@ -0,0 +1,9 @@
+__pycache__
+.coverage
+*.egg-info
+_build
+build
+dist
+coverage.xml
+report.xml
+version.py

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

Pipfile

@@ -0,0 +1,19 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+click = "*"
+
+[dev-packages]
+coverage = "*"
+myst-parser = "*"
+pytest = "*"
+pytest-cov = "*"
+pytest-mock = "*"
+sphinx = "*"
+sphinx-rtd-theme = "*"
+
+[requires]
+python_version = "3.12"

Pipfile.lock

@@ -1,9 +1,17 @@
-# [devminds](https://devminds.ch) Python Project Template
+# Python Project Template by [devminds GmbH](https://devminds.ch)
 
-Directory structure:
+## Directory structure
 
 ```
 ├── docs    Sphinx documentation
 ├── src     Python package source code
 └── tests   Python tests
 ```
+
+## TODO
+
+* Add docs (usage.md) using Sphinx
+* Add pipelines
+  * GitHub: docs/build/test
+  * GitLab: docs/build/test/coverage/deploy
+  * Jenkins: docs/todo|fixme|hack/build/test/coverage

README.md

@@ -0,0 +1,30 @@
+# 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
+SPHINXAPIDOC  ?= sphinx-apidoc
+SOURCEDIR     = .
+BUILDDIR      = _build
+PACKAGEDIR	  = ../src
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Generate API documentation
+apidoc:
+	@$(SPHINXAPIDOC) -f -T -o "$(SOURCEDIR)" "$(PACKAGEDIR)"
+
+# Generate API and HTML documentation
+doc: apidoc
+	@$(SPHINXBUILD) -M html
+
+.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)

docs/Makefile

@@ -0,0 +1,39 @@
+# 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.append(os.path.abspath('../src'))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Python Project Template by devminds GmbH'
+copyright = '2024, Andreas, Thomas'
+author = 'Andreas, Thomas'
+
+# Note: this requires the demo package to be installed
+from demo.version import version  # noqa
+# The full version, including alpha/beta/rc tags
+release = version
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'myst_parser',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.napoleon',
+    'sphinx_rtd_theme'
+]
+
+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']

docs/conf.py

@@ -0,0 +1,29 @@
+demo package
+============
+
+Submodules
+----------
+
+demo.calculate module
+---------------------
+
+.. automodule:: demo.calculate
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+demo.version module
+-------------------
+
+.. automodule:: demo.version
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: demo
+   :members:
+   :undoc-members:
+   :show-inheritance: