From 5207506ae82270eb4541ab5cbe973ae21d96132c Mon Sep 17 00:00:00 2001 From: alexvoss Date: Tue, 24 Mar 2026 21:01:57 -0400 Subject: [PATCH 1/3] feature: add development instructions Signed-off-by: alexvoss --- docs/community/guides/develop.md | 122 +++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 123 insertions(+) create mode 100644 docs/community/guides/develop.md diff --git a/docs/community/guides/develop.md b/docs/community/guides/develop.md new file mode 100644 index 0000000..46148a6 --- /dev/null +++ b/docs/community/guides/develop.md @@ -0,0 +1,122 @@ +--- +icon: lucide/hammer +--- + +# Set up a development environment + +We are providing instructions below to get you up if you want to build Zensical +yourself and if you want to contribute to its development. + +!!! warning "Raise an issue before creating a pull request!" + + Zensical is evolving rapidly and while we work hard to keep the user + experience stable, the implementation is still changing a lot. Since the + grounds are shifting fast, you must open an issue before you create a pull + request so that we can discuss what you want to work on. You must also read + the page on [pull requests], which provides further guidance. + + [pull requests]: ../contribute/pull-requests.md + +## Prerequisites + +Zensical consists of a number of components, each with its own repository. +Depending on which component you want to work on, you will need to install +different development tools. + +To be able to build Zensical, you need to have the following installed: + +- [the `uv` package and project manager][uv] +- a [Rust toolchain] +- [Python] + + [uv]: https://docs.astral.sh/uv/ + [Rust toolchain]: https://rust-lang.org/tools/install/ + [Python]: https://www.python.org/ + +To build the templates, CSS, and TypeScript from the [UI repository], you will +need these additional dependencies: + +- [Node.js] + + [UI repository]: https://github.com/zensical/ui + [Node.js]: https://nodejs.org + +## Development setup + +To build Zensical, you need to: + +1. Check out the code from the [zensical repository] or from your own fork if + you are making a [pull request]: + + [zensical repository]: https://github.com/zensical/zensical/ + [pull request]: ../contribute/pull-requests.md + + ``` + git clone https://github.com/zensical/zensical.git + ``` + +2. Run `uv sync` in the project directory to download and install the + dependencies into the project's virtual environment. + +3. Install the theme content by cloning the [UI repository] and making sure that + the contents of the `dist` directory appear under `python/zensical/templates` + in the Zensical project workspace: + + + === ":material-apple: macOS" + + ``` + git clone https://github.com/zensical/ui.git + ln -s ../../../ui/dist zensical/python/zensical/templates + ln -s ui/dist zensical/python/templates + ``` + + === ":material-linux: Linux" + + ``` + git clone https://github.com/zensical/ui.git + ln -s ui/dist zensical/python/templates + ``` + + === ":fontawesome-brands-windows: Windows (cmd.exe)" + + ``` + git clone https://github.com/zensical/ui.git + mklink ui\dist zensical\python\zensical\templates + ``` + + You need the right to create symbolic links to do this on Windows. + + === ":fontawesome-brands-windows: Windows (Powershell)" + + ``` + git clone https://github.com/zensical/ui.git + New-Item -Type SymbolicLink -Path zensical\python\zensical\templates -Target ui\dist + ``` + + You need the right to create symbolic links to do this on Windows. + +## Building Zensical + +With these preparations out of the way, you can build Zensical by running: + +``` +uv run maturin develop +``` + +## Building the themes + +To build the themes (modern and classic), change into the project directory for +the UI repository and run: + +``` +npm install +npm run build +``` + +## Running Zensical + +To run Zensical from your project, either use `uv run zensical` or activate the +virtual environment so you can just run `zensical`. The latter has the advantage +that it works outside the project directory. + diff --git a/mkdocs.yml b/mkdocs.yml index b82e141..79d08f8 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -233,4 +233,5 @@ nav: - Code of conduct: community/contribute/code-of-conduct.md - Guides: - Reproductions: community/guides/create-a-reproduction.md + - Development: community/guides/develop.md From 39c8929761b5ec5f4e079d176e88a6455e395816 Mon Sep 17 00:00:00 2001 From: alexvoss Date: Tue, 24 Mar 2026 21:05:46 -0400 Subject: [PATCH 2/3] fix: forgot to change path in ln -s for linux Signed-off-by: alexvoss --- docs/community/guides/develop.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/guides/develop.md b/docs/community/guides/develop.md index 46148a6..8b42932 100644 --- a/docs/community/guides/develop.md +++ b/docs/community/guides/develop.md @@ -75,7 +75,7 @@ To build Zensical, you need to: ``` git clone https://github.com/zensical/ui.git - ln -s ui/dist zensical/python/templates + ln -s ../../../ui/dist zensical/python/zensical/templates ``` === ":fontawesome-brands-windows: Windows (cmd.exe)" From 44d219675402efd07d9a1ae1a4ebe59be67f25a5 Mon Sep 17 00:00:00 2001 From: alexvoss Date: Tue, 24 Mar 2026 21:16:55 -0400 Subject: [PATCH 3/3] proof reading, moved running instructions Signed-off-by: alexvoss --- docs/community/guides/develop.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/community/guides/develop.md b/docs/community/guides/develop.md index 8b42932..35cc55f 100644 --- a/docs/community/guides/develop.md +++ b/docs/community/guides/develop.md @@ -4,8 +4,8 @@ icon: lucide/hammer # Set up a development environment -We are providing instructions below to get you up if you want to build Zensical -yourself and if you want to contribute to its development. +We are providing instructions below to get and running you up if you want to +build Zensical yourself and if you want to contribute to its development. !!! warning "Raise an issue before creating a pull request!" @@ -68,7 +68,6 @@ To build Zensical, you need to: ``` git clone https://github.com/zensical/ui.git ln -s ../../../ui/dist zensical/python/zensical/templates - ln -s ui/dist zensical/python/templates ``` === ":material-linux: Linux" @@ -85,7 +84,7 @@ To build Zensical, you need to: mklink ui\dist zensical\python\zensical\templates ``` - You need the right to create symbolic links to do this on Windows. + __Note:__ You need the right to create symbolic links to do this on Windows. === ":fontawesome-brands-windows: Windows (Powershell)" @@ -94,7 +93,7 @@ To build Zensical, you need to: New-Item -Type SymbolicLink -Path zensical\python\zensical\templates -Target ui\dist ``` - You need the right to create symbolic links to do this on Windows. + __Note:__ You need the right to create symbolic links to do this on Windows. ## Building Zensical @@ -104,6 +103,12 @@ With these preparations out of the way, you can build Zensical by running: uv run maturin develop ``` +## Running Zensical + +To run Zensical from your project, either use `uv run zensical` or activate the +virtual environment so you can just run `zensical`. The latter has the advantage +that it works outside the project directory. + ## Building the themes To build the themes (modern and classic), change into the project directory for @@ -114,9 +119,5 @@ npm install npm run build ``` -## Running Zensical - -To run Zensical from your project, either use `uv run zensical` or activate the -virtual environment so you can just run `zensical`. The latter has the advantage -that it works outside the project directory. - +Since the `dist` directory is symlinked into the Zensical project, the build +artifacts will be immediately picked up by any new runs of Zensical.