Skip to content

Commit 1169c3b

Browse files
llucaxllucax
committed
Generate documentation using mkdocs
This adds support to the cookiecutter template to generate documentation using `mkdocs` (and `mkdocstrings` for automated API documentation). Signed-off-by: Leandro Lucarella <[email protected]>
1 parent 8547615 commit 1169c3b

File tree

16 files changed

+361
-9
lines changed

16 files changed

+361
-9
lines changed

‎cookiecutter/cookiecutter.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
"local_extensions.keywords",
2929
"local_extensions.pypi_package_name",
3030
"local_extensions.python_package",
31+
"local_extensions.src_path",
3132
"local_extensions.title"
3233
]
3334
}

‎cookiecutter/hooks/post_gen_project.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,9 @@ def main() -> None:
6666
print(". .venv/bin/activate")
6767
print("pip install .[dev-noxfile]")
6868
print("nox")
69+
print("# To generate and serve the documentation:")
70+
print("pip install .[dev-mkdocs]")
71+
print("mkdocs serve")
6972
print()
7073
if warnings := do_sanity_checks():
7174
for warning in warnings:

‎cookiecutter/local_extensions.py‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,25 @@ def title(cookiecutter: dict[str, str]) -> str:
107107
assert False, f"Unhandled repository type {repo_type!r}"
108108

109109

110+
@_simple_filter # type: ignore[misc]
111+
def src_path(cookiecutter: dict[str, str]) -> str:
112+
"""Build a default source path for the project.
113+
114+
Args:
115+
cookiecutter: The cookiecutter context.
116+
117+
Returns:
118+
The default source path.
119+
"""
120+
match cookiecutter["type"]:
121+
case "api":
122+
return "py"
123+
case "actor" | "lib" | "app" | "model":
124+
return "src"
125+
case _ as repo_type:
126+
assert False, f"Unhandled repository type {repo_type!r}"
127+
128+
110129
@_simple_filter # type: ignore[misc]
111130
def keywords(cookiecutter: dict[str, str]) -> str:
112131
"""Extend cookiecutter["keywords"] with predefined ones by repository type.

‎cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,61 @@ nox -R -s pylint -- test/test_*.py
110110
nox -R -s mypy -- test/test_*.py
111111
```
112112

113+
### Building the documentation
114+
115+
To build the documentation, first install the dependencies (if you didn't
116+
install all `dev` dependencies):
117+
118+
```sh
119+
python -m pip install -e .[dev-mkdocs]
120+
```
121+
122+
Then you can build the documentation (it will be written in the `site/`
123+
directory):
124+
125+
```sh
126+
mkdocs build
127+
```
128+
129+
Or you can just serve the documentation without building it using:
130+
131+
```sh
132+
mkdocs serve
133+
```
134+
135+
Your site will be updated **live** when you change your files (provided that
136+
you used `pip install -e .`, beware of a common pitfall of using `pip install`
137+
without `-e`, in that case the API reference won't change unless you do a new
138+
`pip install`).
139+
140+
To build multi-version documentation, we use
141+
[mike](https://github.com/jimporter/mike). If you want to see how the
142+
multi-version sites looks like locally, you can use:
143+
144+
```sh
145+
mike deploy my-version
146+
mike set-default my-version
147+
mike serve
148+
```
149+
150+
`mike` works in mysterious ways. Some basic information:
151+
152+
* `mike deploy` will do a `mike build` and write the results to your **local**
153+
`gh-pages` branch. `my-version` is an arbitrary name for the local version
154+
you want to preview.
155+
* `mike set-default` is needed so when you serve the documentation, it goes to
156+
your newly produced documentation by default.
157+
* `mike serve` will serve the contents of your **local** `gh-pages` branch. Be
158+
aware that, unlike `mkdocs serve`, changes to the sources won't be shown
159+
live, as the `mike deploy` step is needed to refresh them.
160+
161+
Be careful not to use `--push` with `mike deploy`, otherwise it will push your
162+
local `gh-pages` branch to the `origin` remote.
163+
164+
That said, if you want to test the actual website in **your fork**, you can
165+
always use `mike deploy --push --remote your-fork-remote`, and then access the
166+
GitHub pages produced for your fork.
167+
113168
## Releasing
114169

115170
These are the steps to create a new release:

‎cookiecutter/{{cookiecutter.github_repo_name}}/docs/CONTRIBUTING.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
--8<-- "CONTRIBUTING.md"

‎cookiecutter/{{cookiecutter.github_repo_name}}/docs/SUMMARY.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
* [Home](index.md)
2+
{%- if cookiecutter.type == "api" %}
3+
* [Python API Reference](reference/)
4+
{%- else %}
5+
* [API Reference](reference/)
6+
{%- endif %}
7+
* [Contributing](CONTRIBUTING.md)

‎cookiecutter/{{cookiecutter.github_repo_name}}/docs/css/mkdocstrings.css‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
/* Recommended style from:
2+
* https://mkdocstrings.github.io/python/customization/#recommended-style-material
3+
* With some additions from:
4+
* https://github.com/mkdocstrings/mkdocstrings/blob/master/docs/css/mkdocstrings.css
5+
*/
6+
7+
/* Indentation. */
8+
div.doc-contents:not(.first) {
9+
padding-left: 25px;
10+
border-left: .05rem solid var(--md-typeset-table-color);
11+
}
12+
13+
/* Indentation. */
14+
div.doc-contents:not(.first) {
15+
padding-left: 25px;
16+
border-left: 4px solid rgba(230, 230, 230);
17+
margin-bottom: 80px;
18+
}
19+
20+
/* Avoid breaking parameters name, etc. in table cells. */
21+
td code {
22+
word-break: normal !important;
23+
}
24+
25+
/* Mark external links as such. */
26+
a.autorefs-external::after {
27+
/* https://primer.style/octicons/arrow-up-right-24 */
28+
background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="rgb(0, 0, 0)" d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
29+
content: ' ';
30+
31+
display: inline-block;
32+
position: relative;
33+
top: 0.1em;
34+
margin-left: 0.2em;
35+
margin-right: 0.1em;
36+
37+
height: 1em;
38+
width: 1em;
39+
border-radius: 100%;
40+
background-color: var(--md-typeset-a-color);
41+
}
42+
a.autorefs-external:hover::after {
43+
background-color: var(--md-accent-fg-color);
44+
}

‎cookiecutter/{{cookiecutter.github_repo_name}}/docs/css/style.css‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
/* Based on:
2+
* https://github.com/mkdocstrings/mkdocstrings/blob/master/docs/css/style.css
3+
*/
4+
5+
/* Increase logo size */
6+
.md-header__button.md-logo {
7+
padding-bottom: 0.2rem;
8+
padding-right: 0;
9+
}
10+
.md-header__button.md-logo img {
11+
height: 1.5rem;
12+
}
13+
14+
/* Mark external links as such (also in nav) */
15+
a.external:hover::after, a.md-nav__link[href^="https:"]:hover::after {
16+
/* https://primer.style/octicons/link-external-16 */
17+
background-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill="rgb(233, 235, 252)" d="M10.604 1h4.146a.25.25 0 01.25.25v4.146a.25.25 0 01-.427.177L13.03 4.03 9.28 7.78a.75.75 0 01-1.06-1.06l3.75-3.75-1.543-1.543A.25.25 0 0110.604 1zM3.75 2A1.75 1.75 0 002 3.75v8.5c0 .966.784 1.75 1.75 1.75h8.5A1.75 1.75 0 0014 12.25v-3.5a.75.75 0 00-1.5 0v3.5a.25.25 0 01-.25.25h-8.5a.25.25 0 01-.25-.25v-8.5a.25.25 0 01.25-.25h3.5a.75.75 0 000-1.5h-3.5z"></path></svg>');
18+
height: 0.8em;
19+
width: 0.8em;
20+
margin-left: 0.2em;
21+
content: ' ';
22+
display: inline-block;
23+
}
24+
25+
/* More space at the bottom of the page */
26+
.md-main__inner {
27+
margin-bottom: 1.5rem;
28+
}

‎cookiecutter/{{cookiecutter.github_repo_name}}/docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
--8<-- "README.md"

‎cookiecutter/{{cookiecutter.github_repo_name}}/docs/logo.png‎

55.9 KB
Loading

0 commit comments

Comments
 (0)