create proper docs website

[anmorgunov]

Greptile Summary

This PR introduces a proper documentation website for CalcFlow by adding a full docs/ directory of Markdown pages, a zensical.toml site configuration, and a GitHub Actions workflow to build and deploy the site to GitHub Pages on every push to master/main. The .gitignore is updated to stop ignoring docs/ and *.md files (both previously excluded) and instead ignore the site/ build output.

Key changes:

• 11 new documentation pages covering quick-start, concepts, all major API guides (parsing, inputs, geometry, SLURM, agentic workflows), and developer references (parsers, testing, schema versioning)
• zensical.toml configures the site name, nav structure, theme (light/dark/auto palettes with Lucide icons), and fonts
• .github/workflows/docs.yml deploys the built site to GitHub Pages via the standard upload-pages-artifact / deploy-pages action pair
• pyproject.toml / uv.lock add zensical>=0.0.26 to dev dependencies with its transitive deps pinned in the lockfile

Two style issues were found in the CI workflow: the pip install zensical step is unpinned (inconsistent with the uv.lock pin used everywhere else in the repo), and there is no concurrency group to prevent overlapping Pages deployments on rapid pushes.

Confidence Score: 4/5

• Safe to merge — the documentation content is accurate and the two CI issues are non-blocking style improvements.
• All documentation content is accurate and consistent with the codebase API. The two issues in the workflow (unpinned install and missing concurrency group) are best-practice gaps rather than functional blockers — the first deployment will succeed on the current version. The score is 4 rather than 5 because the unpinned install creates a real reproducibility risk over time.
• .github/workflows/docs.yml — unpinned zensical install and missing concurrency group.

Important Files Changed

Filename	Overview
.github/workflows/docs.yml	New CI workflow that builds and deploys docs to GitHub Pages; has two style issues: unpinned pip install zensical (inconsistent with uv.lock) and missing concurrency group to prevent overlapping deployments.
.gitignore	Removed the old docs/ and *.md ignore rules (docs now live in the repo) and added site/ to ignore the zensical build output; clean and correct change.
zensical.toml	New docs site configuration for the zensical static site generator; nav structure, theme palettes, and font settings all look correct and match the added documentation files.
pyproject.toml	Adds zensical>=0.0.26 to dev dependencies; no issues.
docs/index.md	Homepage for the docs site; accurate feature summary, installation instructions, and supported programs table all consistent with the codebase.
docs/quick-start.md	Five-step quick-start guide covering parse, serialize, build input, export, and runtime API discovery; all code snippets are consistent with the described API.
docs/concepts.md	Explains immutable data models, the block-parser architecture, the fluent input API, zero-dependency design, schema versioning, and the self-documenting API; accurate and well-structured.
docs/guides/parsing.md	Comprehensive parsing guide covering all result fields, TDDFT, ADC, charges, multipole moments, serialization, and spectrum broadening; code examples are consistent with the codebase API.
docs/guides/inputs.md	Detailed guide for building CalculationInput objects; covers TDDFT, solvation, MOM, RI approximations, and exporting; all setter signatures match the described API.
docs/guides/geometry.md	Guide to the geometry, trajectory, annotated geometry, and topology APIs; no issues found.
docs/guides/slurm.md	Guide to SlurmJob for generating HPC submission scripts; code examples are self-consistent and complete.
docs/guides/agentic.md	Agentic/LLM workflow guide with one-liners and multi-step examples; uv run --with calcflow pattern is accurate; the Hartree→eV conversion uses 27.211 (an approximation), which is acceptable in documentation examples.
docs/developers/parsers.md	Developer guide for writing block parsers; step-by-step recipe and worked MullikenChargesParser example are consistent with the documented AGENTS.md parser conventions.
docs/developers/testing.md	Developer testing guide covering the four-level pyramid (unit, contract, integration, regression) with concrete examples; fully consistent with the test strategy described in AGENTS.md.
docs/developers/schema-versioning.md	Schema versioning guide explaining when to bump schema_version, how to write sequential migrations, and forward-incompatibility detection; consistent with the versioning rules in AGENTS.md.
uv.lock	Lockfile updated with zensical==0.0.26 and its transitive dependencies (click, deepmerge, markdown, pymdown-extensions, pyyaml); no issues.

Sequence Diagram

sequenceDiagram
    participant GH as GitHub (push to master)
    participant CI as docs.yml workflow
    participant Pages as GitHub Pages API
    participant Site as Live Docs Site

    GH->>CI: trigger on push
    CI->>CI: configure-pages
    CI->>CI: checkout@v5
    CI->>CI: setup-python@v5
    CI->>CI: pip install zensical
    CI->>CI: zensical build --clean → site/
    CI->>Pages: upload-pages-artifact (path: site/)
    Pages-->>CI: artifact ID
    CI->>Pages: deploy-pages
    Pages-->>CI: page_url
    Pages->>Site: publish new docs build

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: .github/workflows/docs.yml
Line: 24

Comment:
**Unpinned dependency installation — inconsistent with lockfile**

`pip install zensical` fetches the *latest* available version from PyPI at build time, meaning the CI could use a different version than what's pinned in `uv.lock` (`0.0.26`). Every other workflow in this repo uses `uv sync` with the lockfile for reproducibility.

A consistent approach that reuses the lockfile:

```suggestion
      - run: pip install uv && uv sync --group dev
      - run: uv run zensical build --clean
```

Or, if keeping `pip`, at minimum pin to the locked version:

```
- run: pip install "zensical==0.0.26"
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: .github/workflows/docs.yml
Line: 12-16

Comment:
**Missing concurrency group — overlapping deployments possible**

Without a `concurrency` group, rapid back-to-back pushes to `master` (e.g., a merge followed by a tag push) can queue two simultaneous Pages deployments. The second run may fail with a `deployment_not_found` error or silently overwrite the first.

Add a concurrency block immediately after the `on:` trigger:

```
concurrency:
  group: pages
  cancel-in-progress: false
```

Using `cancel-in-progress: false` (rather than `true`) ensures the *latest* build always completes rather than being cancelled mid-deployment.

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: 8d9cad8}

Greptile also left 2 inline comments on this PR.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a brand new, comprehensive documentation website for the CalcFlow project. The documentation is designed to be a central resource for understanding CalcFlow's core principles, learning how to use its various features for parsing quantum chemistry outputs and generating inputs, and guiding developers on contributing to the library. It aims to make the project more accessible and easier to navigate for all users, from beginners to advanced contributors.

Highlights

• New Documentation Website: A comprehensive documentation website has been created using zensical, providing detailed guides for users and developers.
• Enhanced Project Accessibility: The new documentation covers core concepts, API usage, developer guidelines, and practical workflows, significantly improving the project's usability.
• Updated Build Configuration: The .gitignore file was updated to properly exclude documentation build artifacts, and zensical was added as a development dependency.

Changelog

• .gitignore
  • Updated to ignore the site/ directory, which contains the generated documentation output.
  • Removed the exclusion for the docs/ directory itself.
• docs/concepts.md
  • Added a new document detailing CalcFlow's foundational concepts, including immutable data models, parser architecture, fluent input API, zero dependencies, self-documenting API, and schema versioning.
• docs/developers/parsers.md
  • Added a developer guide on writing BlockParsers, covering the protocol, PeekableIterator, ParseState, and common pitfalls.
• docs/developers/schema-versioning.md
  • Added documentation explaining the schema versioning strategy for JSON serialization, including when to bump versions and how to implement migrations.
• docs/developers/testing.md
  • Added a guide on the four levels of testing (unit, contract, integration, regression), test directory structure, fixtures, and best practices for testing input builders.
• docs/guides/agentic.md
  • Added a guide on agentic and LLM workflows, featuring the CalcFlow OpenCode Agent, uv run --with calcflow usage, API navigation, common one-liners, and multi-step workflow examples.
• docs/guides/geometry.md
  • Added a guide on CalcFlow's geometry API, covering Geometry, Trajectory, AnnotatedGeometry, and topology tools like bond detection and aromaticity analysis.
• docs/guides/inputs.md
  • Added a comprehensive guide on building CalculationInput objects, detailing construction, level of theory, task types, spin/charge, compute resources, TDDFT, solvation, atomic charge analysis, SCF convergence, MOM, RI approximations, program-specific options, exporting, and serialization.
• docs/guides/parsing.md
  • Added a detailed guide on parsing output files, covering Q-Chem and ORCA parsers, termination checking, energetics, SCF results, molecular orbitals, atomic charges, multipole moments, TDDFT/TDA/ADC excited states, geometry, timing, serialization, and spectrum broadening.
• docs/guides/slurm.md
  • Added a guide on generating SLURM job scripts using SlurmJob, including environment modules, script generation, and examples for Q-Chem and ORCA.
• docs/index.md
  • Added the main index page for the documentation website, providing an overview of CalcFlow, its features, installation instructions, supported programs and properties, a quick example, and links to getting started guides.
• docs/quick-start.md
  • Added a quick start guide for CalcFlow, covering installation, parsing output files, serialization, building calculation inputs, and runtime API discovery.
• pyproject.toml
  • Added zensical as a development dependency for documentation generation.
• uv.lock
  • Updated dependency lock file to include zensical and its transitive dependencies.
• zensical.toml
  • Added a new configuration file for the zensical documentation generator, defining site metadata, navigation structure, theme settings, and social links.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/docs.yml

Activity

• The author, anmorgunov, has initiated the creation of a comprehensive documentation website for the CalcFlow project.
• This activity involves adding numerous new Markdown files for documentation content and configuring the zensical documentation generator.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive documentation website for the CalcFlow library, built with zensical. It includes detailed guides for users and developers, covering everything from parsing outputs and building inputs to the internal architecture and testing strategies. The changes also correctly update the project's dependencies and .gitignore to support the new documentation build process. The documentation is well-written and structured. I have one suggestion to improve the file handling in code examples for better robustness and consistency.