# Faust Libraries

This repository contains the source code and the documentation of the DSP libraries of the [Faust Programming Language](https://faust.grame.fr). 

Here is the [online documentation](https://faustlibraries.grame.fr) of the Faust libraries (which also serves as a proper README for this repository).

### Prerequisites
- you must have awk and [mkdocs](https://www.mkdocs.org/) installed.
- you must have the Faust source code installed. You can get it from [github](https://github.com/grame-cncm/faust).

###  WARNING: adding new files

Be sure to add new files in the `doc/docs`, and **not** in the `docs` which is the folder generated by the build process.

### Building the documentation

The build process is based on `make` located in the `doc` folder. Building the documentation site is based on [mkdocs](https://www.mkdocs.org/).
To install the required components type:

To generate all these files type:
~~~~~~~~~~~~~~~~
$ make install
~~~~~~~~~~~~~~~~

### Testing and generating

You can test the web site using the mkdoc embedded web server. This server also scan any change in the source directory and refresh the pages dynamically which is really convenient for the development process. To launch the server type:
~~~~~~~~~~~~~~~~
$ make serve
~~~~~~~~~~~~~~~~

When ready, you can generate the documentation web site. Type:
~~~~~~~~~~~~~~~~
$ make build
~~~~~~~~~~~~~~~~
The web site will be available from the `site` folder at the root of the `faustlibraries` folder

More details on the build process:
~~~~~~~~~~~~~~~~
$ make help
~~~~~~~~~~~~~~~~

### Faust Library JSON Exports

This repository can also generate machine-readable JSON exports of the Faust
library documentation directly from the `.lib` sources.

The generator is:

```bash
scripts/build_faust_doc_index.py
```

It parses documentation blocks from the library sources, starting from
`stdfaust.lib`, follows `library("...")` and `import("...")` directives, and
extracts for each documented symbol:

- `summary`
- `usage`
- `params`
- `notes`
- `io` with `inSignals` / `outSignals` when derivable
- `testCode`
- `references`
- `source`

Two JSON layouts are supported:

- monolithic: one full JSON file containing all libraries and symbols
- split: one compact global index plus one detailed JSON file per module

Default Make targets:

```bash
make doc-index
make doc-index-split
```

Default output locations:

- `make doc-index` writes `tests/faust-doc-index.json`
- `make doc-index-split` writes:
  - `tests/faust-doc-index.json`
  - `tests/faust-doc/index.json`
  - `tests/faust-doc/modules/*.json`

You can override the output paths:

```bash
make doc-index DOC_INDEX_OUTPUT=/tmp/faust-doc-index.json
make doc-index-split DOC_INDEX_OUTPUT=/tmp/faust-doc-index.json DOC_INDEX_SPLIT_DIR=/tmp/faust-doc
```

You can also run the generator directly:

```bash
python3 scripts/build_faust_doc_index.py --repo-root . --output tests/faust-doc-index.json --pretty
python3 scripts/build_faust_doc_index.py --repo-root . --output tests/faust-doc-index.json --split-output-dir tests/faust-doc --pretty
```

The split layout is recommended for LLM or retrieval-based use because it avoids
loading the whole documentation into context for every request.

### Local Documentation Query API

The repository also ships with a local query tool that reproduces the Faust
library documentation operations used in `faustforge`:

```bash
scripts/faust_doc_api.py
```

Supported operations:

- `search_faust_lib`
- `get_faust_symbol`
- `list_faust_module`
- `get_faust_examples`
- `explain_faust_symbol_for_goal`

The tool can read either:

- the monolithic export `tests/faust-doc-index.json`
- the split export `tests/faust-doc/index.json`

If `--index` is omitted, it tries these defaults in that order:

1. `tests/faust-doc/index.json`
2. `tests/faust-doc-index.json`

Examples:

```bash
python3 scripts/faust_doc_api.py --pretty search_faust_lib reverb --limit 5
python3 scripts/faust_doc_api.py --pretty search_faust_lib filter --module filters --limit 10

python3 scripts/faust_doc_api.py --pretty get_faust_symbol de.delay
python3 scripts/faust_doc_api.py --pretty list_faust_module delays --limit 20
python3 scripts/faust_doc_api.py --pretty get_faust_examples delay
python3 scripts/faust_doc_api.py --pretty explain_faust_symbol_for_goal re.springreverb "build a metallic spring reverb"
```

To force a specific index location:

```bash
python3 scripts/faust_doc_api.py --index tests/faust-doc-index.json --pretty get_faust_symbol aa.Rsqrt
python3 scripts/faust_doc_api.py --index tests/faust-doc --pretty list_faust_module filters --limit 10
```

Operation semantics mirror `faustforge`:

- `search_faust_lib(query, limit?, module?)`
  searches symbols by name, qualified name, summary, and source file without
  loading full docs into context
- `get_faust_symbol(symbol)`
  returns the full symbol entry plus close alternatives
- `list_faust_module(module, limit?)`
  lists symbols from one library module such as `delays` or `filters`
- `get_faust_examples(symbolOrModule, limit?)`
  returns the `#### Test` snippets for a symbol or module
- `explain_faust_symbol_for_goal(symbol, goal)`
  builds an action-oriented explanation for a concrete DSP objective

The `make clean` target removes the generated JSON artifacts by default:

- `tests/faust-doc-index.json`
- `tests/faust-doc/`

### Publishing 

Publishing is handled by GitHub Actions. Pushing to the main branch will build and deploy the site.

### LLMs

The site exposes an `llms.txt` file generated from `doc/docs/llms.txt` and published at `https://faustlibraries.grame.fr/llms.txt`.

### WARNING!!

- never delete the **doc/docs/CNAME** file (which is mandatory for the final generated site to work)
