From 5207506ae82270eb4541ab5cbe973ae21d96132c Mon Sep 17 00:00:00 2001 From: alexvoss Date: Tue, 24 Mar 2026 21:01:57 -0400 Subject: [PATCH 1/6] 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/6] 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/6] 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. From a283d11df6d70cf2a9879f6172fa08191fe155f8 Mon Sep 17 00:00:00 2001 From: Alexander Voss Date: Wed, 25 Mar 2026 08:49:11 -0400 Subject: [PATCH 4/6] Update docs/community/guides/develop.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Timothée Mazzucotelli Signed-off-by: Alexander Voss --- 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 35cc55f..1775ee3 100644 --- a/docs/community/guides/develop.md +++ b/docs/community/guides/develop.md @@ -4,7 +4,7 @@ icon: lucide/hammer # Set up a development environment -We are providing instructions below to get and running you up if you want to +We are providing instructions below to get you up and running 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!" From b3235a61b17ef027d46e42a8edaebf93f5a63a1b Mon Sep 17 00:00:00 2001 From: alexvoss Date: Wed, 25 Mar 2026 09:23:52 -0400 Subject: [PATCH 5/6] edits after feedback Signed-off-by: alexvoss --- docs/community/guides/develop.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/docs/community/guides/develop.md b/docs/community/guides/develop.md index 1775ee3..f03bb58 100644 --- a/docs/community/guides/develop.md +++ b/docs/community/guides/develop.md @@ -19,7 +19,7 @@ build Zensical yourself and if you want to contribute to its development. ## Prerequisites -Zensical consists of a number of components, each with its own repository. +Zensical consists of a number of projects, each with its own repository. Depending on which component you want to work on, you will need to install different development tools. @@ -84,7 +84,8 @@ To build Zensical, you need to: mklink ui\dist zensical\python\zensical\templates ``` - __Note:__ You need the right to create symbolic links to do this on Windows. + __Note:__ You need the permission to create symbolic links to do this on + Windows. === ":fontawesome-brands-windows: Windows (Powershell)" @@ -93,7 +94,8 @@ To build Zensical, you need to: New-Item -Type SymbolicLink -Path zensical\python\zensical\templates -Target ui\dist ``` - __Note:__ You need the right to create symbolic links to do this on Windows. + __Note:__ You need the permission to create symbolic links to do this on + Windows. ## Building Zensical @@ -105,9 +107,13 @@ 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. +To run Zensical within its own project folder, you can use `uv run zensical`. +Alternatively, activate the project virtual environment so you can just run +`zensical` and run it in other directories. + +If you want to install your compiled version of Zensical in another project, +activate its virtual environment and run `pip install -e +/path/to/zensical/project`. ## Building the themes From a4e925a78eda762e0cbbeaffbe6b51b20c33ca6c Mon Sep 17 00:00:00 2001 From: alexvoss Date: Wed, 25 Mar 2026 09:48:05 -0400 Subject: [PATCH 6/6] fix: mklink syntax 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 f03bb58..e87d1a7 100644 --- a/docs/community/guides/develop.md +++ b/docs/community/guides/develop.md @@ -81,7 +81,7 @@ To build Zensical, you need to: ``` git clone https://github.com/zensical/ui.git - mklink ui\dist zensical\python\zensical\templates + mklink zensical\python\zensical\templates ui\dist ``` __Note:__ You need the permission to create symbolic links to do this on