diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml deleted file mode 100644 index d7eed9b..0000000 --- a/.github/workflows/build.yml +++ /dev/null @@ -1,26 +0,0 @@ -name: Build Docs - -# Builds the site in strict mode, so a broken link or a nav entry -# pointing at a missing page fails the PR rather than the deploy. - -on: - pull_request: - push: - branches: [main] - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Set up uv - uses: astral-sh/setup-uv@v6 - with: - enable-cache: true - - - name: Install docs dependencies - run: uv sync --locked - - - name: Build site - run: uv run zensical build --strict diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..fc09d90 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,58 @@ +name: Docs + +# Builds the site in strict mode on every PR, so a broken link or a nav +# entry pointing at a missing page fails the PR rather than the deploy. +# On main, the same build is then published to GitHub Pages (Settings → +# Pages → Source must be "GitHub Actions"). + +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + + - name: Set up uv + uses: astral-sh/setup-uv@v10.2.0 + with: + enable-cache: true + + - name: Install docs dependencies + run: uv sync --locked + + - name: Build site + run: uv run zensical build --clean --strict + + - name: Upload site + if: github.ref == 'refs/heads/main' + uses: actions/upload-pages-artifact@v5 + with: + path: site + + deploy: + if: github.ref == 'refs/heads/main' + needs: build + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + # Deploys queue rather than cancel each other, so one is never + # interrupted mid-publish. + concurrency: + group: pages + cancel-in-progress: false + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v5 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..c441ecc --- /dev/null +++ b/LICENSE @@ -0,0 +1,29 @@ +BSD 3-Clause License + +Copyright (c) 2026, Centre National de la Recherche Scientifique (CNRS) and +The Regents of the University of California + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md index 0f81c4f..20f0b9e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,38 @@ -# docs +# Lightcone Research Stack documentation -Documentation for the Lightcone Research stack +[![Docs](https://img.shields.io/github/actions/workflow/status/LightconeResearch/docs/docs.yml?branch=main&style=flat&label=docs&color=darkgreen)](https://docs.lightconeresearch.org) +[![License](https://img.shields.io/badge/License-BSD_3--Clause-426b78.svg?style=flat)](LICENSE) + +The **Lightcone Research Stack** is [Lightcone Research](https://lightconeresearch.org/)'s +tooling for research analyses described with [ASTRA](https://astra-spec.org/latest/) +(Agentic Schema for Transparent Research Analysis). You describe an analysis in an +`astra.yaml` specification; the stack validates it and takes care of the rest — +execution, environments, and provenance. + +**→ Read the documentation at ** + +## Where to start + +- [Install](https://docs.lightconeresearch.org/user/install/) — uv, git, and the `lc` command +- [Getting started](https://docs.lightconeresearch.org/user/getting-started/) — your first analysis, from `lc init` to a published result +- [Core concepts](https://docs.lightconeresearch.org/user/concepts/) — projects, output identity, and how provenance is recorded +- [Running on a cluster](https://docs.lightconeresearch.org/user/cluster/) — SLURM, containers on HPC, and parallel filesystems +- [Troubleshooting](https://docs.lightconeresearch.org/user/troubleshooting/) — common errors and how to fix them + +## Components + +| Component | What it does | Repository | +| --- | --- | --- | +| **lightcone-cli** | The `lc` CLI: project scaffolding, locked environments, sandboxed execution, and the provenance layer | [LightconeResearch/lightcone-cli](https://github.com/LightconeResearch/lightcone-cli) | +| **astra-tools** | The SDK and `astra` CLI for ASTRA specifications: schema, validation, and evidence verification helpers | [LightconeResearch/astra-tools](https://github.com/LightconeResearch/astra-tools) | + +## Feedback + +The stack is in early alpha, and bug reports, design challenges, and use cases it +doesn't cover yet are welcome. Report a problem with a tool on that tool's +repository; report a problem with the documentation itself — a page that is wrong, +unclear, or out of date — [here](https://github.com/LightconeResearch/docs/issues). + +## License + +BSD 3-Clause — see [LICENSE](LICENSE). diff --git a/docs/index.md b/docs/index.md index 3146407..e1b65bc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,16 +1,17 @@ -# lightcone-cli +# Lightcone Research Stack -**lightcone-cli** is [Lightcone Research][lr]'s execution layer for -[**ASTRA**][astra] (Agentic Schema for Transparent Research Analysis). -It serves as the machinery that ties an analysis `astra.yaml` specification to a tree -of materialized outputs. +The **Lightcone Research Stack** is [Lightcone Research][lr]'s tooling for research +analyses described with [**ASTRA**][astra] (Agentic Schema for Transparent Research +Analysis). +You describe an analysis in an `astra.yaml` specification; the stack validates it and +takes care of the rest — execution, environments, and provenance. !!! warning "Alpha development" - lightcone-cli is in **early alpha**. The CLI and the execution layer are - still moving — expect breaking changes between minor versions. Bug reports, design - challenges, and use cases the tooling doesn't yet cover are exactly what we want to - hear at this stage; please open an issue on the - [GitHub repo](https://github.com/LightconeResearch/lightcone-cli/issues). + The stack is in **early alpha**. Its tools are still moving — expect breaking + changes between minor versions. Bug reports, design challenges, and use cases the + tooling doesn't yet cover are exactly what we want to hear at this stage; please + open an issue on the [repository](https://github.com/LightconeResearch) of the tool + concerned. ## Choose your path to the documentation @@ -28,7 +29,7 @@ of materialized outputs. --- - In depth tour of the software architecture and API docs, as well as contribution instructions, aimed for + In-depth tour of lightcone-cli's architecture and internals, as well as contribution instructions, aimed at contributors and maintainers. [Developer corner](maintainer.md){ .md-button .md-button--primary } @@ -37,7 +38,7 @@ of materialized outputs. --- -## Two libraries, one toolchain +## Components of the stack
diff --git a/pyproject.toml b/pyproject.toml index fc6816d..0cb0631 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [project] name = "lightcone-docs" version = "0.0.0" -description = "Documentation for the Lightcone Research stack" +description = "Documentation for the Lightcone Research Stack" requires-python = ">=3.11" dependencies = [ "zensical>=0.0.34", diff --git a/zensical.toml b/zensical.toml index e4ef834..630d5e6 100644 --- a/zensical.toml +++ b/zensical.toml @@ -1,6 +1,7 @@ [project] -site_name = "lightcone-cli" -site_description = "Execution layer for ASTRA research pipelines" +site_name = "Lightcone Research Stack" +site_description = "Documentation for the Lightcone Research Stack" +site_url = "https://docs.lightconeresearch.org/" site_author = "Lightcone Research Team" repo_url = "https://github.com/LightconeResearch/docs" repo_name = "LightconeResearch/docs"