Add Zensical documentation option#738
Conversation
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`
- Use cookiecutter.project_short_description - Remove bullet on deploying docs
VeckoTheGecko
left a comment
VeckoTheGecko
left a comment
There was a problem hiding this comment.
Do we need to make any updates to https://learn.scientific-python.org/development/guides/docs/#writing-documentation ? I think we're fine right?
There was a problem hiding this comment.
docs/index.md, docs/markdown.md and zensical.toml are all provided by zensical new .
| session.install("{% if cookiecutter.backend != "mesonpy" %}-e{% endif %}.", *doc_deps) | ||
|
|
||
| if session.interactive: | ||
| session.run("zensical", "serve", *session.posargs) |
There was a problem hiding this comment.
serve doesn't have a clean option
| ] | ||
| {%- elif cookiecutter.docs == "zensical" %} | ||
| docs = [ | ||
| "zensical>=0.0.20", |
There was a problem hiding this comment.
I wanted to avoid a hard pin, but this may cause problems if zensical.toml changes
|
Hmmm, there's a bit of a conflict between the markdown flavouring in the Zensical SSG (+material mkdocs) and the prettier pre-commit hook https://github.com/VeckoTheGecko/zensical_cookie_test/actions/runs/21571031386/job/62150095699#step:5:339 -!!! warning "Needs configuration"
- 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.
+!!! warning "Needs configuration" 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.Interestingly since we use Material for Mkdocs for the mkdocs option, I think this is an error that also effects the mkdocs option @squidfunk what's the best way to autoformat your flavour of markdown? (e.g., a specific prettier config?) EDIT: Grammar :) |
|
There are some formatters that support a subset of Python Markdown, but I currently use none, so I can't recommend one. Once we move to CommonMark, any popular Markdown formatter should work. Also, I would kindly ask you to ask for such things on our Discord. As you can probably imagine, we're currently getting hammered with support requests, which eats into our time pushing Zensical out of alpha, so I'd appreciate it, if you would ask the community for help |
|
Of course! Didnt think about that. Ill join the discord :) |
Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
|
I'd prefer lightweight config vs. template output, but that's okay for now, and maybe we could even add a nox job to regenerate the template output. |
Agreed, though thought to err on the side of template output for traceability since this is still in alpha. I'll try fix the linting problems. I'll remove some of the markdown in the example page since its non-standard markdown and its conflicting with prettier (I'd rather the user - or another PR - deals with the fact of #738 (comment) ) |
|
Thanks! I might see if I can add a regenerate option in nox later. |
3 participants
Fixes #737 1
PR done with reference to:
items) https://docs.readthedocs.com/platform/stable/intro/zensical.html#deploying-zensical-on-read-the-docs
zensical new .zensicalSince Zensical is in active development, the example docs (both config and pages) from
zensical new .is likely to change quite a bit. I'm not sure if we should trim downzensical.toml, or just manually periodically update it based onzensical new ..Testing
Manually by creating a quick example repo at https://github.com/VeckoTheGecko/zensical_cookie_test (see README-ROOT.md )
The RTD deployment for this example is at https://zensical-cookie-test.readthedocs.io/en/latest/
Not sure how to go about automated testing (or further integration into nox testing we have here) - not sure if its needed, from what I can tell the docs building, integration into RTD, etc are left to be manually tested
AI disclaimer
No AI used.
📚 Documentation preview 📚: https://scientific-python-cookie--738.org.readthedocs.build/
Footnotes
I know this hasn't been discussed yet - feel free to reject this PR if this isn't something you're willing to maintain at this point. I thought a PR would be helpful to see the maintainer burden ↩