[V4] Documentation scaffold

[ConorWilliams]

A scaffold for libforks next-gen docs, only task/env is done, the rest is mostly placeholders

Summary by CodeRabbit

• Documentation

  • Restructured and expanded API documentation with organized modules (core, batteries, schedulers, algorithm).
  • Added comprehensive getting-started and contributing guides.
  • Added benchmarks documentation.
  • Reorganized tour and index pages for improved navigation.

• Chores

  • Configured GitHub Pages automated documentation deployment.
  • Added Python project metadata and documentation build tooling.
  • Updated .gitignore and Python version configuration.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: acb9af97-75de-45f1-a088-ae5a076aa438

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch v4-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 8

🧹 Nitpick comments (1)

.github/workflows/docs.yml (1)

25-25: ⚡ Quick win

Pin zensical to avoid non-deterministic deploy breakages.

Line 25 installs the latest release implicitly; a future upstream release can break docs deploys unexpectedly. Although pyproject.toml specifies zensical>=0.0.41, the workflow should align with this constraint or use a bounded range to prevent unexpected breakages.

Proposed change

-      - run: pip install zensical
+      - run: pip install "zensical>=0.0.41,<0.1"

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/docs.yml at line 25, Replace the unpinned installer
command "pip install zensical" in the docs workflow with a pinned or bounded
version to prevent non-deterministic breakages; for example change it to "pip
install zensical==0.0.41" or use a bounded range like "pip install
'zensical>=0.0.41,<0.1.0'" so the workflow aligns with the pyproject.toml
constraint and avoids pulling future breaking releases.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/api/core/env.md`:
- Around line 27-34: The struct definition for context_generic is missing the
terminating semicolon; update the declaration so the closing brace of struct
context_generic is followed by a semicolon (i.e., change the end of the struct
containing the template operator() that returns lf::task<void, Context> to end
with "};"). Ensure you modify the context_generic struct that defines
operator()(lf::env<Context>, int) -> lf::task<void, Context> to include the
semicolon after the brace.

In `@docs/api/core/projected.md`:
- Around line 40-41: The constrained-template syntax is invalid because
projectable is declared as projectable<Fn, Context, I>; fix both the source
(src/core/projected.cxx) and docs (docs/api/core/projected.md) by changing the
template declaration to name Fn first and apply the constraint via a
requires-clause, e.g. use "template<typename Fn, worker_context Context,
std::indirectly_readable I> requires projectable<Fn, Context, I> using projected
= /*...*/;" so that the concept parameters (Fn, Context, I) match the
projectable concept.

In `@docs/api/core/receiver.md`:
- Around line 142-147: The warning admonition currently uses an indented code
block causing MD046; change it to a fenced code block by moving the explanatory
line and adding a ```cpp fence before the example and a closing ``` after it so
the snippet `auto value = std::move(recv).get();` (showing use of
rvalue-qualified get) is inside a fenced block; update the admonition around the
`get`/`recv` text so the warning message line is plain text and the code is
wrapped with ```cpp ... ``` to satisfy markdownlint.

In `@docs/api/core/task.md`:
- Around line 21-23: Fix the grammar in the documentation sentence describing
the return type for coroutines/async-functions: replace the incorrect
contraction "it's typedefs" with the possessive "its typedefs" in the
description of the return type so the sentence reads correctly about the type
having no public interface other than its typedefs.

In `@docs/api/schedulers.md`:
- Around line 83-86: The admonition "!!! note" block is being treated as an
indented code block; fix it by adding a blank line immediately after the "!!!
note" marker and unindenting the body text (remove the leading four-space
indent) so the note body is a normal paragraph; update the block that starts
with "!!! note" and the following indented lines in docs/api/schedulers.md
accordingly.

In `@tour.md`:
- Around line 1-5: The document contains a duplicated title "A tour of libfork"
as both an H1 and an H2; remove one of these headers to avoid repetition—either
delete the initial H1 "# A tour of libfork" or the later "## A tour of libfork"
so only a single, appropriately leveled heading remains and update surrounding
text if needed to keep structure consistent.

In `@zensical.toml`:
- Line 12: Update the site_description key in zensical.toml to reflect the new
docs' positioning: replace the reference to "C++20's coroutines" with wording
that highlights C++26 module-based design (e.g., mention "C++26 modules" or
"module-based C++26 API") so the value for site_description aligns with the
module-oriented docs and avoids mixed messaging.
- Around line 39-40: The edit_uri setting currently points to a branch-specific
path ("edit/v4-docs/docs/") which will break edit links after merging; update
the edit_uri key (edit_uri) to point to the main branch path (e.g.,
"edit/main/docs/") or a branch-agnostic value used by your docs system so "Edit
this page" links remain correct after merge.

---

Nitpick comments:
In @.github/workflows/docs.yml:
- Line 25: Replace the unpinned installer command "pip install zensical" in the
docs workflow with a pinned or bounded version to prevent non-deterministic
breakages; for example change it to "pip install zensical==0.0.41" or use a
bounded range like "pip install 'zensical>=0.0.41,<0.1.0'" so the workflow
aligns with the pyproject.toml constraint and avoids pulling future breaking
releases.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ec26f971-5726-466c-af86-be8905ed139d

📥 Commits

Reviewing files that changed from the base of the PR and between 46bae8a and d25a5fb.

⛔ Files ignored due to path filters (13)

• .legacy/docs/_static/android-chrome-192x192.png is excluded by !**/*.png
• .legacy/docs/_static/android-chrome-512x512.png is excluded by !**/*.png
• .legacy/docs/_static/apple-touch-icon.png is excluded by !**/*.png
• .legacy/docs/_static/favicon-16x16.png is excluded by !**/*.png
• .legacy/docs/_static/favicon-32x32.png is excluded by !**/*.png
• .legacy/docs/_static/favicon.ico is excluded by !**/*.ico
• docs/favicon/android-chrome-192x192.png is excluded by !**/*.png
• docs/favicon/android-chrome-512x512.png is excluded by !**/*.png
• docs/favicon/apple-touch-icon.png is excluded by !**/*.png
• docs/favicon/favicon-16x16.png is excluded by !**/*.png
• docs/favicon/favicon-32x32.png is excluded by !**/*.png
• docs/favicon/favicon.ico is excluded by !**/*.ico
• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (32)

• .github/workflows/docs.yml
• .gitignore
• .python-version
• docs/api.md
• docs/api/algorithm.md
• docs/api/batteries.md
• docs/api/core/cancellation.md
• docs/api/core/concepts.md
• docs/api/core/context.md
• docs/api/core/env.md
• docs/api/core/exceptions.md
• docs/api/core/handles.md
• docs/api/core/index.md
• docs/api/core/invoke.md
• docs/api/core/projected.md
• docs/api/core/receiver.md
• docs/api/core/scheduling.md
• docs/api/core/scope.md
• docs/api/core/task.md
• docs/api/index.md
• docs/api/schedulers.md
• docs/benchmarks.md
• docs/contributing.md
• docs/favicon/site.webmanifest
• docs/getting-started.md
• docs/index.md
• docs/structure.md
• docs/tour.md
• pyproject.toml
• src/core/task.cxx
• tour.md
• zensical.toml

💤 Files with no reviewable changes (4)

• src/core/task.cxx
• docs/structure.md
• docs/api.md
• .gitignore