Skip to content

Commit ab443cc

Browse files
VeckoTheGeckohenryiii
VeckoTheGecko
and
henryiii
authored
Add Zensical documentation option (#738)
* Add Zensical With reference to: - ReadTheDocs Zensical setup (adjusting to mesh with current cookie items) https://docs.readthedocs.com/platform/stable/intro/zensical.html#deploying-zensical-on-read-the-docs - Using files generated by `zensical new .` - Using help docs included in `zensical` * Update Zensical config - Use cookiecutter.project_short_description - Remove bullet on deploying docs * RTD fix indentation * Fix Zensical RTD build * Update ordering * ci: add zensical Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * Formatting * Formatting --------- Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> Co-authored-by: Henry Schreiner <henryschreineriii@gmail.com>
1 parent ad4434f commit ab443cc

11 files changed

+621
-14
lines changed

‎.github/workflows/reusable-cookie.yml‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -48,17 +48,17 @@ jobs:
4848
- name: Test pybind11
4949
run: nox -s 'tests(pybind11, novcs)' -s 'tests(pybind11, vcs, sphinx)'
5050

51-
- name: Test scikit-build
52-
run: nox -s 'tests(skbuild, novcs)' -s 'tests(skbuild, vcs, sphinx)'
51+
- name: Test scikit-build (zensical)
52+
run: nox -s 'tests(skbuild, novcs)' -s 'tests(skbuild, vcs, zensical)'
5353

5454
- name: Test poetry
5555
run: nox -s 'tests(poetry, novcs)' -s 'tests(poetry, vcs, sphinx)'
5656

57-
- name: Test flit
57+
- name: Test flit (mkdocs)
5858
run: nox -s 'tests(flit, novcs)' -s 'tests(flit, vcs, mkdocs)'
5959

60-
- name: Test uv
61-
run: nox -s 'tests(uv, novcs, sphinx)'
60+
- name: Test uv (zensical)
61+
run: nox -s 'tests(uv, novcs, zensical)'
6262

6363
- name: Test pdm
6464
run: nox -s 'tests(pdm, novcs)' -s 'tests(pdm, vcs, sphinx)'
@@ -130,11 +130,11 @@ jobs:
130130
- name: Test poetry
131131
run: |
132132
nox -s 'nox(poetry, novcs, sphinx)'
133-
nox -s 'nox(poetry, novcs, mkdocs)' -- docs
133+
nox -s 'nox(poetry, novcs, zensical)' -- docs
134134
135135
- name: Test flit
136136
run: |
137-
nox -s 'nox(flit, novcs, mkdocs)'
137+
nox -s 'nox(flit, novcs, zensical)'
138138
nox -s 'nox(flit, novcs, mkdocs)' -- docs
139139
140140
- name: Test pdm
@@ -144,8 +144,8 @@ jobs:
144144
145145
- name: Test maturin
146146
run: |
147-
nox -s 'nox(maturin, novcs, sphinx)'
148-
nox -s 'nox(maturin, novcs, sphinx)' -- docs
147+
nox -s 'nox(maturin, novcs, zensical)'
148+
nox -s 'nox(maturin, novcs, zensical)' -- docs
149149
150150
- name: Test hatch
151151
run: |

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,8 @@ templates for Python packages?
1717
clearly documented and every tool described, and everything is kept in sync.
1818
- Ten different backends to choose from for building packages.
1919
- Optional VCS versioning for most backends.
20-
- Selection for your preferred documentation engine (Sphinx or MkDocs).
20+
- Selection for your preferred documentation engine (Sphinx, MkDocs, or
21+
Zensical).
2122
- Template generation tested in GitHub Actions using nox.
2223
- Supports generation with [copier][], [cookiecutter][], and [cruft][].
2324
- Supports GitHub Actions if targeting a `github.com` url (the default), and
@@ -151,8 +152,7 @@ backports structure with a small typing example.
151152
- One of several popular licenses
152153
- A pylint nox target can be used to run pylint, which integrated GHA
153154
annotations
154-
- A ReadTheDocs-ready Sphinx or MkDocs `docs/` folder and `docs`
155-
dependency-group
155+
- A ReadTheDocs-ready `docs/` folder and `docs` dependency-group
156156
- A `tests/` folder and pytest `test` dependency-group
157157
- A dev group for `uv run` integration
158158
- A noxfile is included with a few common targets

‎cookiecutter.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
"mesonpy",
1919
"maturin"
2020
],
21-
"docs": ["sphinx", "mkdocs"],
21+
"docs": ["sphinx", "mkdocs", "zensical"],
2222
"vcs": true,
2323
"__year": "{% now 'utc', '%Y' %}",
2424
"__project_slug": "{{ cookiecutter.project_name | lower | replace('-', '_') | replace('.', '_') }}",
@@ -49,7 +49,8 @@
4949
"docs": {
5050
"__prompt__": "Choose your documentation tool",
5151
"sphinx": "Sphinx",
52-
"mkdocs": "MkDocs"
52+
"mkdocs": "MkDocs",
53+
"zensical": "Zensical (alpha)"
5354
},
5455
"vcs": "Use version control for versioning"
5556
}

‎copier.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,7 @@ docs:
8888
choices:
8989
"Sphinx": sphinx
9090
"MkDocs": mkdocs
91+
"Zensical (alpha)": zensical
9192
# [[[end]]]
9293

9394
# [[[cog print(cc.vcs.yaml()) ]]]

‎noxfile.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@
4242
class Docs(enum.Enum):
4343
Sphinx = "sphinx"
4444
MkDocs = "mkdocs"
45+
Zensical = "zensical"
4546

4647

4748
DIR = Path(__file__).parent.resolve()

‎{{cookiecutter.project_name}}/.readthedocs.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,8 @@ build:
1717
docs $READTHEDOCS_OUTPUT/html
1818
{%- elif cookiecutter.docs == 'mkdocs' %}
1919
- uv run mkdocs build --site-dir $READTHEDOCS_OUTPUT/html
20+
{%- elif cookiecutter.docs == 'zensical' %}
21+
- uv run zensical build
22+
- mkdir -p $READTHEDOCS_OUTPUT/html/
23+
- cp --recursive site/* $READTHEDOCS_OUTPUT/html/
2024
{%- endif %}

‎{{cookiecutter.project_name}}/docs/{% if cookiecutter.docs == 'zensical' %}index.md{% endif %}‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
icon: lucide/rocket
3+
---
4+
5+
# Get started
6+
7+
For full documentation visit [zensical.org](https://zensical.org/docs/).
8+
9+
## Commands
10+
11+
- [`zensical new`][new] - Create a new project
12+
- [`zensical serve`][serve] - Start local web server
13+
- [`zensical build`][build] - Build your site
14+
15+
[new]: https://zensical.org/docs/usage/new/
16+
[serve]: https://zensical.org/docs/usage/preview/
17+
[build]: https://zensical.org/docs/usage/build/
18+
19+
## Examples
20+
21+
### Admonitions
22+
23+
> Go to [documentation](https://zensical.org/docs/authoring/admonitions/)
24+
25+
!!! note
26+
27+
This is a **note** admonition. Use it to provide helpful information.
28+
29+
!!! warning
30+
31+
This is a **warning** admonition. Be careful!
32+
33+
### Details
34+
35+
> Go to
36+
> [documentation](https://zensical.org/docs/authoring/admonitions/#collapsible-blocks)
37+
38+
??? info "Click to expand for more info"
39+
40+
This content is hidden until you click to expand it.
41+
Great for FAQs or long explanations.
42+
43+
## Code Blocks
44+
45+
> Go to [documentation](https://zensical.org/docs/authoring/code-blocks/)
46+
47+
```python hl_lines="2" title="Code blocks"
48+
def greet(name):
49+
print(f"Hello, {name}!") # (1)!
50+
51+
52+
greet("Python")
53+
```
54+
55+
1. > Go to
56+
> [documentation](https://zensical.org/docs/authoring/code-blocks/#code-annotations)
57+
58+
Code annotations allow to attach notes to lines of code.
59+
60+
Code can also be highlighted inline: `#!python print("Hello, Python!")`.
61+
62+
## Content tabs
63+
64+
> Go to [documentation](https://zensical.org/docs/authoring/content-tabs/)
65+
66+
=== "Python"
67+
68+
``` python
69+
print("Hello from Python!")
70+
```
71+
72+
=== "Rust"
73+
74+
``` rs
75+
println!("Hello from Rust!");
76+
```
77+
78+
## Diagrams
79+
80+
> Go to [documentation](https://zensical.org/docs/authoring/diagrams/)
81+
82+
```mermaid
83+
graph LR
84+
A[Start] --> B{Error?};
85+
B -->|Yes| C[Hmm...];
86+
C --> D[Debug];
87+
D --> B;
88+
B ---->|No| E[Yay!];
89+
```
90+
91+
## Footnotes
92+
93+
> Go to [documentation](https://zensical.org/docs/authoring/footnotes/)
94+
95+
Here's a sentence with a footnote.[^1]
96+
97+
Hover it, to see a tooltip.
98+
99+
[^1]: This is the footnote.
100+
101+
## Formatting
102+
103+
> Go to [documentation](https://zensical.org/docs/authoring/formatting/)
104+
105+
- ==This was marked (highlight)==
106+
- ^^This was inserted (underline)^^
107+
- ~~This was deleted (strikethrough)~~
108+
- H~2~O
109+
- A^T^A
110+
- ++ctrl+alt+del++
111+
112+
## Icons, Emojis
113+
114+
> Go to [documentation](https://zensical.org/docs/authoring/icons-emojis/)
115+
116+
- :sparkles: `:sparkles:`
117+
- :rocket: `:rocket:`
118+
- :tada: `:tada:`
119+
- :memo: `:memo:`
120+
- :eyes: `:eyes:`
121+
122+
## Maths
123+
124+
> Go to [documentation](https://zensical.org/docs/authoring/math/)
125+
126+
$$
127+
\cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k}
128+
$$
129+
130+
!!! warning "Needs configuration"
131+
132+
Note that MathJax is included via a `script` tag on this page and is not configured in the generated default configuration to avoid including it in a pages that do not need it. See the documentation for details on how to configure it on all your pages if they are more Maths-heavy than these simple starter pages.
133+
134+
<script id="MathJax-script" async src="https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js"></script>
135+
<script>
136+
window.MathJax = {
137+
tex: {
138+
inlineMath: [["\\(", "\\)"]],
139+
displayMath: [["\\[", "\\]"]],
140+
processEscapes: true,
141+
processEnvironments: true
142+
},
143+
options: {
144+
ignoreHtmlClass: ".*|",
145+
processHtmlClass: "arithmatex"
146+
}
147+
};
148+
</script>
149+
150+
## Task Lists
151+
152+
> Go to
153+
> [documentation](https://zensical.org/docs/authoring/lists/#using-task-lists)
154+
155+
- [x] Install Zensical
156+
- [x] Configure `zensical.toml`
157+
- [x] Write amazing documentation
158+
- [ ] Deploy anywhere
159+
160+
## Tooltips
161+
162+
> Go to [documentation](https://zensical.org/docs/authoring/tooltips/)
163+
164+
[Hover me][example]
165+
166+
[example]: https://example.com "I'm a tooltip!"

‎{{cookiecutter.project_name}}/docs/{% if cookiecutter.docs == 'zensical' %}markdown.md{% endif %}‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
icon: simple/markdown
3+
---
4+
5+
# Markdown in 5min
6+
7+
## Headers
8+
9+
```
10+
# H1 Header
11+
## H2 Header
12+
### H3 Header
13+
#### H4 Header
14+
##### H5 Header
15+
###### H6 Header
16+
```
17+
18+
## Text formatting
19+
20+
```
21+
**bold text**
22+
*italic text*
23+
***bold and italic***
24+
~~strikethrough~~
25+
`inline code`
26+
```
27+
28+
## Links and images
29+
30+
```
31+
[Link text](https://example.com)
32+
[Link with title](https://example.com "Hover title")
33+
![Alt text](image.jpg)
34+
![Image with title](image.jpg "Image title")
35+
```
36+
37+
## Lists
38+
39+
```
40+
Unordered:
41+
- Item 1
42+
- Item 2
43+
- Nested item
44+
45+
Ordered:
46+
1. First item
47+
2. Second item
48+
3. Third item
49+
```
50+
51+
## Blockquotes
52+
53+
```
54+
> This is a blockquote
55+
> Multiple lines
56+
>> Nested quote
57+
```
58+
59+
## Code blocks
60+
61+
````
62+
```javascript
63+
function hello() {
64+
console.log("Hello, world!");
65+
}
66+
```
67+
````
68+
69+
## Tables
70+
71+
```
72+
| Header 1 | Header 2 | Header 3 |
73+
|----------|----------|----------|
74+
| Row 1 | Data | Data |
75+
| Row 2 | Data | Data |
76+
```
77+
78+
## Horizontal rule
79+
80+
```
81+
---
82+
or
83+
***
84+
or
85+
___
86+
```
87+
88+
## Task lists
89+
90+
```
91+
- [x] Completed task
92+
- [ ] Incomplete task
93+
- [ ] Another task
94+
```
95+
96+
## Escaping characters
97+
98+
```
99+
Use backslash to escape: \* \_ \# \`
100+
```
101+
102+
## Line breaks
103+
104+
```
105+
End a line with two spaces
106+
to create a line break.
107+
108+
Or use a blank line for a new paragraph.
109+
```

0 commit comments

Comments
 (0)