Skip to content

Commit 31262af

Browse files
github-actions[bot]github-actions[bot]
committed
Deployed 3eb3b35 with MkDocs version: 1.6.1
0 parents  commit 31262af

56 files changed

Lines changed: 10692 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.nojekyll‎

Whitespace-only changes.

‎404.html‎

Lines changed: 407 additions & 0 deletions
Large diffs are not rendered by default.

‎README.qmd‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
---
2+
title: Python package template
3+
format: gfm
4+
---
5+
6+
<!-- Automatically generated, uses README.qmd to modify README.md -->
7+
8+
A python package template that contains everything you need to:
9+
10+
- **create**
11+
- ~~configure~~
12+
- `test`
13+
- _document_
14+
- <u>deploy</u>
15+
16+
<br>
17+
18+
```
19+
root/
20+
├── package_name/ - Main package directory
21+
│ ├── __init__.py
22+
│ └── main.py/
23+
├── tests/ - Unit tests
24+
│ ├── __init__.py
25+
│ └── test_main.py
26+
├── docs/ - Documentation
27+
│ ├── README.qmd - Quarto document that generates README.md
28+
│ ├── index.md - Main page
29+
│ ├── contributing.md - A contributing guide
30+
│ ├── examples.md - Usage examples
31+
│ ├── stylesheets/ - CSS for the documentation
32+
│ └── reference/ - API reference of the package
33+
├── .github/workflows/ - CI/CD
34+
│ ├── doc.yaml - Deploy website
35+
│ ├── lint.yaml - Check code with ruff
36+
│ ├── type.yaml - Check static typing with ty
37+
│ ├── tests.yaml - Run unit tests
38+
│ └── pypi.yaml - New PyPI release
39+
├── scripts/ - Miscellaneous
40+
│ └── release.sh - Trigger PyPI release
41+
├── pyproject.toml - Configuration, metadata, dependencies
42+
├── README.md - Project overview, generated by README.qmd
43+
├── Makefile - Common commands needed when developing
44+
├── LICENSE - License file
45+
├── .gitignore - Git ignore rules
46+
├── .pre-commit-config.yaml - Pre commit hooks
47+
└── mkdocs.yaml - Documentation website configuration
48+
```
49+
50+
<br><br>
51+
52+
53+
54+
## How to use this template
55+
56+
### Create a new repo
57+
58+
* Click on `Use this template` and `Create a new repository`
59+
* Clone your repo
60+
61+
```bash
62+
git clone https://github.com/your_name/package_name.git
63+
```
64+
65+
<br>
66+
67+
### Replace with your package info
68+
69+
* Replace **all** `your_name` with your GitHub username or organization
70+
* Replace **all** `package_name` with your actual package
71+
* Replace info in `pyproject.toml`
72+
* Change the `LICENSE` file to your actual license (optional)
73+
74+
<br>
75+
76+
### Install dependencies
77+
78+
```bash
79+
uv sync --all-groups
80+
uv pip install -e .
81+
uv run pre-commit install
82+
```
83+
84+
<br>
85+
86+
### Run tests
87+
88+
```bash
89+
make test
90+
```
91+
92+
To generate a code coverage badge and see your code coverage, run:
93+
94+
```bash
95+
make coverage
96+
```
97+
98+
<br>
99+
100+
### Documentation website
101+
102+
The documentation is based on [mkdocstrings](https://mkdocstrings.github.io/), but feel free to use another framework.
103+
104+
You only have to set up [GitHub Pages](https://pages.github.com/) to the `gh-pages` branch, and `.github/workflows/doc.yaml` will handle the deployment.
105+
106+
* Preview locally:
107+
108+
```bash
109+
make preview
110+
```
111+
112+
* Footer of the site:
113+
114+
The footer of the documentation website is defined in `overrides/partials/footer.html`. If you don't know HTML/CSS, chatGPT can help you here!
115+
116+
* Change main color:
117+
118+
In `docs/stylesheets/style.css`, change the color value to change the overall style of site:
119+
120+
```css
121+
:root {
122+
--primary-color: #0096c7;
123+
}
124+
```
125+
126+
<br>
127+
128+
### Make a new PyPI release
129+
130+
New PyPI releases are made via 2 scripts:
131+
132+
* `release.sh`
133+
134+
* When you run `.scripts/release.sh 1.0.0` (to release the 1.0.0 version, for instance), it will commit, tag that commit and push.
135+
* `.github/workflows/pypi.yaml`
136+
137+
* When a git tag matching `v1.2.3` format is pushed, it will make a new PyPI release (in short).
138+
139+
This relies on [trusted publishing](https://docs.pypi.org/trusted-publishers/), which you need to configure. This step is important (on security aspects), so make sure you understand what is happening. Feel free to spend some time reading the scripts and the official documentation.
140+
141+
Since the distribution of new versions is reserved for a few people, feel free to remove it from the git tracker with:
142+
143+
```bash
144+
git rm --cached scripts/release.sh
145+
```
146+
147+
If you don't plan to make PyPI releases, just delete `.scripts/release.sh` and `.github/workflows/pypi.yaml`.
148+
149+
<br>
150+
151+
152+
### Update the README
153+
154+
The `README.md` file is dynamically generated by `docs/README.qmd`, a [Quarto document](https://quarto.org/).
155+
156+
This is optional (you can use a plain `README.md` and delete `docs/README.qmd`), but it has many benefits:
157+
158+
* it is just markdown too
159+
* there are [lots of customization options](https://quarto.org/docs/authoring/markdown-basics.html)
160+
* you can include code (for example, dynamic content)
161+
162+
```{python}
163+
from package_name import add_digit
164+
165+
# The output here is not hardcoded
166+
print(add_digit(2, 5))
167+
```
168+
169+
It works perfectly well with most IDEs. You can install Quarto [here](https://quarto.org/docs/get-started/).
170+
171+
To generate `README.md`, run (make sure your venv is activated):
172+
173+
```bash
174+
make readme
175+
```
176+
177+
<br>
178+
<br>
179+
180+
Still have some questions? Open an [issue](https://github.com/y-sunflower/python-package-template/issues)!

‎assets/_mkdocstrings.css‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
2+
/* Avoid breaking parameter names, etc. in table cells. */
3+
.doc-contents td code {
4+
word-break: normal !important;
5+
}
6+
7+
/* No line break before first paragraph of descriptions. */
8+
.doc-md-description,
9+
.doc-md-description>p:first-child {
10+
display: inline;
11+
}
12+
13+
/* No text transformation from Material for MkDocs for H5 headings. */
14+
.md-typeset h5 .doc-object-name {
15+
text-transform: none;
16+
}
17+
18+
/* Max width for docstring sections tables. */
19+
.doc .md-typeset__table,
20+
.doc .md-typeset__table table {
21+
display: table !important;
22+
width: 100%;
23+
}
24+
25+
.doc .md-typeset__table tr {
26+
display: table-row;
27+
}
28+
29+
/* Defaults in Spacy table style. */
30+
.doc-param-default {
31+
float: right;
32+
}
33+
34+
/* Parameter headings must be inline, not blocks. */
35+
.doc-heading-parameter {
36+
display: inline;
37+
}
38+
39+
/* Default font size for parameter headings. */
40+
.md-typeset .doc-heading-parameter {
41+
font-size: inherit;
42+
}
43+
44+
/* Prefer space on the right, not the left of parameter permalinks. */
45+
.doc-heading-parameter .headerlink {
46+
margin-left: 0 !important;
47+
margin-right: 0.2rem;
48+
}
49+
50+
/* Backward-compatibility: docstring section titles in bold. */
51+
.doc-section-title {
52+
font-weight: bold;
53+
}
54+
55+
/* Backlinks crumb separator. */
56+
.doc-backlink-crumb {
57+
display: inline-flex;
58+
gap: .2rem;
59+
white-space: nowrap;
60+
align-items: center;
61+
vertical-align: middle;
62+
}
63+
.doc-backlink-crumb:not(:first-child)::before {
64+
background-color: var(--md-default-fg-color--lighter);
65+
content: "";
66+
display: inline;
67+
height: 1rem;
68+
--md-path-icon: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M8.59 16.58 13.17 12 8.59 7.41 10 6l6 6-6 6z"/></svg>');
69+
-webkit-mask-image: var(--md-path-icon);
70+
mask-image: var(--md-path-icon);
71+
width: 1rem;
72+
}
73+
.doc-backlink-crumb.last {
74+
font-weight: bold;
75+
}
76+
77+
/* Symbols in Navigation and ToC. */
78+
:root, :host,
79+
[data-md-color-scheme="default"] {
80+
--doc-symbol-parameter-fg-color: #df50af;
81+
--doc-symbol-attribute-fg-color: #953800;
82+
--doc-symbol-function-fg-color: #8250df;
83+
--doc-symbol-method-fg-color: #8250df;
84+
--doc-symbol-class-fg-color: #0550ae;
85+
--doc-symbol-module-fg-color: #5cad0f;
86+
87+
--doc-symbol-parameter-bg-color: #df50af1a;
88+
--doc-symbol-attribute-bg-color: #9538001a;
89+
--doc-symbol-function-bg-color: #8250df1a;
90+
--doc-symbol-method-bg-color: #8250df1a;
91+
--doc-symbol-class-bg-color: #0550ae1a;
92+
--doc-symbol-module-bg-color: #5cad0f1a;
93+
}
94+
95+
[data-md-color-scheme="slate"] {
96+
--doc-symbol-parameter-fg-color: #ffa8cc;
97+
--doc-symbol-attribute-fg-color: #ffa657;
98+
--doc-symbol-function-fg-color: #d2a8ff;
99+
--doc-symbol-method-fg-color: #d2a8ff;
100+
--doc-symbol-class-fg-color: #79c0ff;
101+
--doc-symbol-module-fg-color: #baff79;
102+
103+
--doc-symbol-parameter-bg-color: #ffa8cc1a;
104+
--doc-symbol-attribute-bg-color: #ffa6571a;
105+
--doc-symbol-function-bg-color: #d2a8ff1a;
106+
--doc-symbol-method-bg-color: #d2a8ff1a;
107+
--doc-symbol-class-bg-color: #79c0ff1a;
108+
--doc-symbol-module-bg-color: #baff791a;
109+
}
110+
111+
code.doc-symbol {
112+
border-radius: .1rem;
113+
font-size: .85em;
114+
padding: 0 .3em;
115+
font-weight: bold;
116+
}
117+
118+
code.doc-symbol-parameter,
119+
a code.doc-symbol-parameter {
120+
color: var(--doc-symbol-parameter-fg-color);
121+
background-color: var(--doc-symbol-parameter-bg-color);
122+
}
123+
124+
code.doc-symbol-parameter::after {
125+
content: "param";
126+
}
127+
128+
code.doc-symbol-attribute,
129+
a code.doc-symbol-attribute {
130+
color: var(--doc-symbol-attribute-fg-color);
131+
background-color: var(--doc-symbol-attribute-bg-color);
132+
}
133+
134+
code.doc-symbol-attribute::after {
135+
content: "attr";
136+
}
137+
138+
code.doc-symbol-function,
139+
a code.doc-symbol-function {
140+
color: var(--doc-symbol-function-fg-color);
141+
background-color: var(--doc-symbol-function-bg-color);
142+
}
143+
144+
code.doc-symbol-function::after {
145+
content: "func";
146+
}
147+
148+
code.doc-symbol-method,
149+
a code.doc-symbol-method {
150+
color: var(--doc-symbol-method-fg-color);
151+
background-color: var(--doc-symbol-method-bg-color);
152+
}
153+
154+
code.doc-symbol-method::after {
155+
content: "meth";
156+
}
157+
158+
code.doc-symbol-class,
159+
a code.doc-symbol-class {
160+
color: var(--doc-symbol-class-fg-color);
161+
background-color: var(--doc-symbol-class-bg-color);
162+
}
163+
164+
code.doc-symbol-class::after {
165+
content: "class";
166+
}
167+
168+
code.doc-symbol-module,
169+
a code.doc-symbol-module {
170+
color: var(--doc-symbol-module-fg-color);
171+
background-color: var(--doc-symbol-module-bg-color);
172+
}
173+
174+
code.doc-symbol-module::after {
175+
content: "mod";
176+
}
177+
178+
.doc-signature .autorefs {
179+
color: inherit;
180+
border-bottom: 1px dotted currentcolor;
181+
}

‎assets/images/favicon.png‎

1.83 KB
Loading

‎assets/javascripts/bundle.92b07e13.min.js‎

Lines changed: 16 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)