Tools¶
Tools used to develop, build, and document the sustainablefactory project.
Software Inventory and Citations¶
The software bibliography is generated from repository installation manifests
by tools/generate_software_citations.py.
It currently contains 838 package and tool records: 216 Python distributions,
322 Rust crates and tools, 167 Ubuntu packages, 105 npm packages, 8 Lean
packages or toolchains, 15 unique VS Code extensions, 3 runtimes, and 2 browser
installations. Cite an entry with its generated key, for example
[sphinx, n.d.] or [playwright, n.d.].
The generator scans 37 pyproject.toml files, 27 requirements*.txt files,
127 Cargo.toml files, 25 package.json files, 4 lakefile.toml files,
Makefiles, .devcontainer/devcontainer.json, and Dockerfile.e2e. The recursive
scan intentionally includes vendored, example, and test projects. A declaration
in one of those manifests does not mean that package is installed in the main
development container. requirements-dev.txt also references
requirements-meilisearch.txt, which is not present in this checkout, so its
contents cannot be included.
The default container setup is defined by .devcontainer/devcontainer.json
and Dockerfile.e2e: Ubuntu 24.04 system packages, a
Python virtual environment, Node.js 22.x and npm, the Lean toolchain installed
with elan, PyMuPDF 1.28.2 in /opt/pdf-tools, npm dependencies for the root and
e2e/ projects, and Playwright-managed Chromium and Firefox. The devcontainer
post-create step also installs the root project and src/schematool and
src/transform_md as editable Python packages, builds Signals with Lake, and
installs the listed VS Code extensions. Other Makefile targets install
additional, task-specific tools and dependencies; they are not all part of
container creation.
Each BibTeX note records the declaration source and version constraint. These are manifest declarations, not resolved versions or proof that a dependency is present in a particular environment. The catalog does not resolve transitive dependencies from lockfiles, package registries, or system package indexes; Ubuntu package entries identify the Noble repository, not a pinned package revision. Local packages without a declared homepage intentionally have no registry URL. Re-run the generator after changing manifests to refresh the catalog.
Sphinx¶
Commands:
sphinx-build --help
Lean¶
Features:
type verification, theorem modeling, theorem proving
machine-checkable proofs
Commands:
leanleanc
Lean Libraries¶
Mathlib¶
Path:
src/Mathlib
Physlib¶
Path:
src/Physlib
QECLean¶
Path:
src/QECLean
Signals¶
Path:
src/signals
numerical_adapter¶
Path:
src/signals/numerical_adapterFeatures
Rust-based fluid analysis
Verify that Lyapunov exponents predict observed real fluids from JHTDB
Rust code produced from src/signals
cannon_mask_cad.rs
double_slit.rs
madelung_lagrangian.rs
orbital_splat.rs
polariton_spp.rs
thermal_inelastic.rs
Python code produced from src/signals
jhtdb_cutout_probe.py
jhtdb_probe.py
matlab_piv_probe.py
rspid_subset_probe.py
WebGL GLSL Shaders produced from src/signals
double_slit.frag.glsl
double_slit.vert.glsl
orbital_splat.frag.glsl
orbital_split.vert.glsl
Signals blueprint¶
Path:
src/signals/blueprint/src/content.tex
Lake¶
Features
package manager for Lean modules
Commands
lake
Lean Blueprint¶
Features
annotate Lean modules with structured docstrings
Commands
leanblueprint
Lean Architect¶
Features
build Lean modules with Lean Blueprint annotations into HTML
schematool¶
Features
recursively download RDFS and OWL schemas into an on-disk file layout
Commands
schematool --help
transform_md¶
transform_md parses industrial process descriptions (like paper.md) and converts them into a structured graph linked data representation using the Industrial Ontologies Foundry (IOF) and sustainablefactory process schema. [ schema ]
Parser: Extracts steps, properties, and Mermaid diagrams.
RDF Generator: Produces Turtle-star (
.ttl) with reified confidence metrics.Visualizer: Integrated Mermaid diagrams for process flow overview.
Commands
transform_md --help
docindex¶
Features
YAML toctrees and tagged chat overlays
Commands
docindex --help
toctreeyaml¶
The toctreeyaml directive extends Sphinx’s native toctree directive with a
Jupyter Book-compatible YAML tree. It reads _toc.yml by default, or a file
selected with :file::
```{toctreeyaml}
:file: _toc.yml
:maxdepth: 2
```
The same attributes can be supplied inline as YAML content. root,
chapters, nested sections, parts, file, and title are supported.
```{toctreeyaml}
maxdepth: 2
chapters:
- file: readme
- file: schema
title: Project Schema
```
Chat source selection and tag overlays are configured in
docs/_toc.yml under sustainablefactory.chat_sources. Run make chat_overlays to create the chats__all
overlay and one chats/TAG symlink directory for each source-document tag.
The transformation targets use the all overlay and generate only MyST and
notebook outputs; docindex indexes the MyST files.
The optional sphinxcontrib-webmcp extension exposes theme-independent tools
for page context, navigation, documentation metadata, and search through
document.modelContext. Enable it with docindex_webmcp_enabled and configure
the public behavior with docindex_webmcp. It emits webmcp.json from the
Sphinx build, including navigation and compact doctree metadata. WebMCP remains
inactive in browsers that do not implement the API or that deny the tools
permissions policy.
When docindex_searchtools_enhanced is enabled, docs/_templates/search.html
shows native Sphinx and DocIndex as separate modes. Enable either configured
backend under docindex_searchtools.docindex; oxirs.url must accept the existing
form-encoded query request, and meilisearch.url must be reachable from the
browser. Only a Meilisearch public search key may be placed in
public_api_key; never put an administrative key in a static documentation
build.
See Workflow Performance Plan for the staged plan to simplify and accelerate the complete transformation, documentation, and search-index workflow.