Skip to content

Commit 0e46893

Browse files
lambda-sciencelambda-science
committed
Feat: Docs & CI/CD
1 parent ef286fc commit 0e46893

File tree

8 files changed

+229
-1
lines changed

8 files changed

+229
-1
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: ci
2+
on:
3+
push:
4+
branches:
5+
- master
6+
- main
7+
permissions:
8+
contents: write
9+
jobs:
10+
deploy:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
- name: Configure Git Credentials
15+
run: |
16+
git config user.name github-actions[bot]
17+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
18+
- uses: actions/setup-python@v5
19+
with:
20+
python-version: 3.x
21+
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
22+
- uses: actions/cache@v4
23+
with:
24+
key: mkdocs-material-${{ env.cache_id }}
25+
path: .cache
26+
restore-keys: |
27+
mkdocs-material-
28+
- run: pip install mkdocs-material mkdocstrings mkdocstrings-python mkdocs-include-markdown-plugin
29+
- run: mkdocs gh-deploy --force

‎.gitlab-ci.yml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
pages:
2+
stage: deploy
3+
image: python:latest
4+
script:
5+
- pip install mkdocs-material mkdocstrings mkdocstrings-python mkdocs-include-markdown-plugin
6+
- mkdocs build --site-dir public
7+
cache:
8+
key: ${CI_COMMIT_REF_SLUG}
9+
paths:
10+
- .cache/
11+
artifacts:
12+
paths:
13+
- public
14+
rules:
15+
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

‎Makefile‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,21 @@
1+
.PHONY: help
2+
3+
help:
4+
@echo "Usage:"
5+
@echo " make dev Run the package with developer settings"
6+
@echo " make prod Run the pacakge with production settings"
7+
@echo " make test CI: Run tests"
8+
@echo " make cov CI: Run test and calculate coverage"
9+
@echo " make check CI: Lint the code"
10+
@echo " make format CI: Format the code"
11+
@echo " make type CI: Check typing"
12+
@echo " make doc Run local documentation server"
13+
@echo " make build Build the package wheel before publishing to Pypi"
14+
@echo " make publish Publish package to Pypi"
15+
@echo " make dockerbuild Build the docker image"
16+
@echo " make dockerrun Run the docker image"
17+
@echo " make allci Run all CI steps (check, format, type, test coverage)"
18+
119
dev:
220
modern_python_boilerplate
321

‎README.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Modern Python Boilerplate
2+
This is my modern python boilerplate. The goal is to provide a good starting point to develop new python project with most up-to-date tooling, structure and good practices.
3+
4+
# Features
5+
A global `Makefile` to run all the commands. You can run `make help` to see all the available commands.
6+
7+
- **Python Management**
8+
- UV for python version management `.python-version`
9+
- UV for dependency management `pyproject.toml`
10+
- src/package structure
11+
- Usage of Project Script to directly call the package like `$ modern_python_boilerplate`
12+
- **Continuous Integration `make allci`**
13+
- Ruff for linting `make check`
14+
- Ruff for formatting `make format`
15+
- Ty for type checking `make type`
16+
- Pytest for testing `make test`
17+
- Pytest-cov for testing coverage `make cov`
18+
- Pre-commit hooks to make some checks and formatting code before commits `make commit`
19+
- **Documentation**
20+
- Mkdocs for documentation building with Markdown `make doc`
21+
- Automatic build of the API Reference page
22+
- Pre-configured GitHub Action / Gitlab CI for publishing the documentation on Github pages / Gitlab pages
23+
- **Running, Publishing and Deploying**
24+
- Build the pacakge with UV `make build`
25+
- Publish to PyPi with Twine `make publish`
26+
- Dockerfile to run in a container `make dockerbuild` and `make dockerrun`
27+
- DevContainer pre-configured. `.devcontainer/devcontainer.json`
28+
29+
# How to use
30+
1. Delete this README.md to replace by you package one.
31+
2. Replace all occurrence of `modern_python_boilerplate` and `modern-python-boilerplate` and `ModernPythonBoilerplate` by your pacakge name. Including folder names in src/.
32+
3. Get familiar with `make help`, it will show you all the available commands.
33+
34+
***
35+
36+
## Readme Sample for your pacakge
37+
38+
# MyPackage
39+
This is my package. It does some cool stuff.
40+
41+
## Installation
42+
From PyPi: `pip install my_package`
43+
From source: `pip install -e .`
44+
45+
## Usage
46+
Example 1: `my_package --help`
47+
48+
## Contact
49+
Creator and Maintainer: [**Corentin Meyer**, PhD in Biomedical AI](https://cmeyer.fr) <contact@cmeyer.fr>

‎docs/index.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: Home
3+
description: ModernPythonBoilerplate
4+
hide:
5+
- navigation
6+
---
7+
8+
# Modern Python Boilerplate
9+
This is my modern python boilerplate. The goal is to provide a good starting point to develop new python project with most up-to-date tooling, structure and good practices.
10+
11+
# Features
12+
A global `Makefile` to run all the commands. You can run `make help` to see all the available commands.
13+
14+
- **Python Management**
15+
- UV for python version management `.python-version`
16+
- UV for dependency management `pyproject.toml`
17+
- src/package structure
18+
- Usage of Project Script to directly call the package like `$ modern_python_boilerplate`
19+
- **Continuous Integration `make allci`**
20+
- Ruff for linting `make check`
21+
- Ruff for formatting `make format`
22+
- Ty for type checking `make type`
23+
- Pytest for testing `make test`
24+
- Pytest-cov for testing coverage `make cov`
25+
- Pre-commit hooks to make some checks and formatting code before commits `make commit`
26+
- **Documentation**
27+
- Mkdocs for documentation building with Markdown `make doc`
28+
- Automatic build of the API Reference page
29+
- **Running, Publishing and Deploying**
30+
- Build the pacakge with UV `make build`
31+
- Publish to PyPi with Twine `make publish`
32+
- Dockerfile to run in a container `make dockerbuild` and `make dockerrun`
33+
- DevContainer pre-configured. `.devcontainer/devcontainer.json`
34+
35+
# How to use
36+
1. Delete this README.md to replace by you package one.
37+
2. Replace all occurrence of `modern_python_boilerplate` and `modern-python-boilerplate` and `ModernPythonBoilerplate` by your pacakge name. Including folder names in src/.
38+
3. Get familiar with `make help`, it will show you all the available commands.

‎docs/reference.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# API Reference
2+
3+
::: modern_python_boilerplate.main
4+
handler: python
5+
options:
6+
show_root_heading: true
7+
show_source: true

‎mkdocs.yml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
site_name: ModernPythonBoilerplate
2+
site_url: https://github.com/lambda-science/modern-python-boilerplate
3+
site_author: Corentin Meyer
4+
site_description: ModernPythonBoilerplate
5+
theme:
6+
font:
7+
text: Inter
8+
code: JetBrains Mono
9+
icon:
10+
logo: material/file-document-multiple-outline
11+
palette:
12+
# Palette toggle for light mode
13+
- scheme: default
14+
primary: white
15+
toggle:
16+
icon: material/lightbulb
17+
name: Switch to dark mode
18+
19+
# Palette toggle for dark mode
20+
- scheme: slate
21+
primary: black
22+
toggle:
23+
icon: material/lightbulb-outline
24+
name: Switch to light mode
25+
name: material
26+
features:
27+
- navigation.instant
28+
- navigation.top
29+
- navigation.tabs
30+
- search.suggest
31+
- search.highlight
32+
33+
plugins:
34+
- search
35+
- tags
36+
- mkdocstrings:
37+
default_handler: python
38+
handlers:
39+
python:
40+
paths: [ "src" ]
41+
options:
42+
annotations_path: brief
43+
docstring_style: google
44+
- include-markdown:
45+
preserve_includer_indent: true
46+
nav:
47+
- Home: index.md
48+
- API Reference: reference.md
49+
markdown_extensions:
50+
- attr_list
51+
- admonition
52+
- pymdownx.details
53+
- pymdownx.superfences
54+
- tables
55+
- md_in_html
56+
- pymdownx.highlight:
57+
anchor_linenums: true
58+
- pymdownx.inlinehilite
59+
- pymdownx.snippets
60+
- pymdownx.superfences
61+
- pymdownx.emoji:
62+
emoji_index: !!python/name:material.extensions.emoji.twemoji
63+
emoji_generator: !!python/name:material.extensions.emoji.to_svg
64+
65+
repo_url: https://github.com/lambda-science/modern-python-boilerplate
66+
extra:
67+
social:
68+
- icon: material/web
69+
link: https://cmeyer.fr/
70+
- icon: fontawesome/brands/x-twitter
71+
link: https://x.com/corentinm_py

‎src/modern_python_boilerplate/main.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
def hello_world():
1+
def hello_world() -> str:
2+
"""Prints a hello world message."""
23
return "Hello from modern-python-boilerplate!"
34

45

0 commit comments

Comments
 (0)