diplodocus 0.15.0

Build coherent documentation websites for polyglot software projects.
Documentation
# Python, R, Julia, Rust, and C++ API extraction

Diplodocus reads configured API targets and uses native tooling to complete
language semantics and verify documentation examples. Rust extraction invokes
Cargo and rustdoc, including local compilation and build scripts. Runtime-assisted
adapters require callers to prepare compiled packages beforehand. C++ extraction
uses Doxygen without compiling the library. Diplodocus does not install
dependencies. Targets must point to maintained files inside their declared
package and repository boundaries. The [workspace guide](configuration.md) shows
how to declare a target.

## C++ with Doxygen {#cpp-with-doxygen}

C++ extraction requires Doxygen on `PATH`, a prepared checkout, and an explicit
Doxyfile. Use `ecosystem: cpp` and `extractor: doxygen`:

```yaml
packages:
  - id: qualpal
    name: Qualpal
    slug: cpp
    ecosystem: cpp
    repository: source
    path: .
    metadata-path: Doxyfile
    targets:
      - id: api
        extractor: doxygen
        path: Doxyfile
        role: public-api
```

Declare `source` in `repositories` as usual. Both Doxyfile paths can select an
existing site configuration, including a generated `build/Doxyfile.docs`. Prepare
generated configuration with the project's normal configuration step first.

As a headers-only alternative, save a small Doxyfile as `Doxyfile.api` and set
both `metadata-path` and the target `path` to that file. For Qualpal's public
headers, it can contain:

```text
PROJECT_NAME = Qualpal
INPUT = include
RECURSIVE = YES
EXTRACT_PRIVATE = NO
EXTRACT_STATIC = NO
EXCLUDE_SYMBOLS = qualpal::detail qualpal::metrics::detail
WARN_AS_ERROR = YES
```

Set `PROJECT_NUMBER` to the package version, or use a Doxyfile generated by the
project's existing build configuration. `metadata-path` selects the Doxyfile
whose project name, number, and brief supply package metadata. The target
Doxyfile controls API extraction. Both paths may identify the same file.

Diplodocus runs Doxygen from the package root during `check`, `extract`, `build`,
and `serve`. Relative Doxyfile paths use that working directory. Prepare generated
headers and configuration beforehand; Diplodocus does not run CMake or compile
the library. It requests XML in temporary storage, so the Doxyfile does not need
to enable XML output. Custom preprocessing and input filters run as configured.

The wrapper preserves `HAVE_DOT` and disables other output formats. Doxygen can
retain `@dot` descriptions in XML without rendering diagrams or invoking
Graphviz. Doxygen still validates a configured `DOT_PATH`. Native warning
settings, including `WARN_AS_ERROR`, remain effective: invalid references and
other extraction problems still produce diagnostics and can fail extraction.

C++ pages preserve namespaces, types, templates, overloads, and their
documentation. API references can use fully qualified names such as
`qualpal::Qualpal::setWhitePoint`. Overloads retain separate anchors and prose
under their callable family. Doxygen code blocks remain illustrative. Standalone
Doxygen pages, groups, and diagrams are not imported; use content collections
and static figures for guides. The headers-only Doxyfile avoids parsing the
existing site's standalone guides and their assets.

After extraction, `generate` needs neither Doxygen nor the checkout. See the
[C++ extraction contract](https://github.com/jolars/diplodocus/blob/main/docs/ir/cpp-extraction.md) for supported semantics and
source observation boundaries.

## Rust

Rust extraction uses Cargo and rustdoc to document the compiler-selected public
API, including reexports from private modules, macro-generated declarations,
generic signatures, traits, associated items, and implementations. Crate and
module documentation appear alongside item documentation. Hidden items stay out
of the public reference. Type and trait pages group their fields, variants,
methods, and implementations under stable anchors.

Declare one explicit library entry file:

```yaml
packages:
  - id: "eunoia"
    name: "Eunoia"
    slug: "rust"
    ecosystem: "rust"
    repository: "eunoia"
    path: "crates/eunoia"
    metadata-path: "Cargo.toml"
    targets:
      - id: "api"
        extractor: "rust"
        path: "src/lib.rs"
        role: "public-api"
```

Cargo supplies workspace-inherited metadata. Targets must match the library
entry declared by Cargo. Rust extraction currently uses the host target; binary
targets and cross-compilation are unsupported. Cargo's default features remain
enabled unless the target supplies `rust: { default-features: false }`.
Use `rust: { features: ["parallel"] }` to select additional features. Features
apply equally to API extraction and doctests; all features are never enabled
implicitly.

The documentation toolchain is `nightly-2026-09-28`, separate from Diplodocus's
stable compiler and the documented package's toolchain. `devenv shell` prepares
it automatically. Elsewhere, install that nightly with Cargo, rustc, and rustdoc,
and set `DIPLODOCUS_RUST_TOOLCHAIN` to its toolchain root. Diplodocus validates
the compiler identity and rustdoc JSON format before using them. It does not
install the toolchain. Prepare the package's Cargo.lock and cached dependencies
before extraction; all native Cargo commands use `--locked --offline`.

Both `check` and extraction invoke native compiler tooling, which may compile
dependencies and execute build scripts. `check` resolves the actual Rust API and
documentation links but does not run examples. `extract`, `build`, and `serve`
also compile and execute native doctests before publication. Bare fences and
Rust fences follow rustdoc semantics, including hidden setup lines, explicit
editions, `no_run`, `compile_fail`, `should_panic`, and `ignore` attributes.
Snapshots distinguish execution, compilation alone, expected errors, and
explicit skips. Native successful stdout may be absent from the recorded output.

Intra-doc links retain their labels and resolve to local pages or external crate
documentation. Authored semantic links can use the configured package ID and a
Rust path, such as `eunoia::eunoia::Fitter`, or a crate-relative name within that
package, such as `eunoia::Fitter`. Reexports share one canonical item identity.
Source links retain the original definition location.

Snapshots retain Rust declarations, resolved references, input fingerprints,
compiler and dependency evidence, and completed doctest outcomes. Generation
requires neither the checkout nor the Rust toolchain. Compilation artifacts may
be reused, but extraction and doctest outcomes are recomputed on each build.
Failures preserve the previous snapshot and site. The
[Rust extraction contract](https://github.com/jolars/diplodocus/blob/main/docs/ir/rust-extraction.md)
describes the portable representation and native input boundary.

## Python

Python extraction reads `pyproject.toml` metadata and maintained `.py` and
`.pyi` files. It recognizes statically visible functions, classes, methods,
properties, constants, fields, type aliases, overloads, and supported
decorators. A statically resolvable `__all__` controls exports; otherwise,
public definitions and explicit aliases form the visible surface. Maintained
stubs supply public signatures, while implementation docstrings supply prose.
PEP 257 and NumPy-style docstrings provide structured documentation, and simple
`:func:` roles can become cross-references.

Overloaded callables have one reference page containing their public signatures
and implementation docstring. Navigation and search list the callable once.
Individual overload identities remain in snapshots, and references to them link
to the corresponding signature on the callable's page.

Python pages prefer public reexport names over private implementation paths.
For example, a function defined as `datamonger._api.fetch_data` and exported as
`datamonger.fetch_data` uses the latter name in its heading, navigation, and
search result. Both names remain searchable and resolve to the same page.
Snapshots retain the defining name, source location, and export evidence.

Computed exports, conditional definitions, opaque signatures, unsupported
decorators, and other dynamic behavior cannot be inferred safely. Diplodocus
reports the limit instead of guessing an API. For a
public function decorated with `contextlib.contextmanager`, it preserves the
parameters and renders a generator's `Iterator[T]` or `Generator[T, ...]` return
annotation as `AbstractContextManager[T]`. An unsupported decorator on a public
declaration produces a diagnostic, and its callable signature is omitted because
the wrapper may change it. Unsupported decorators on internal declarations do
not prevent extraction of the public surface unless those declarations are
reexported.

Python doctest transcripts execute during `extract`, `build`, and `serve` through
the caller's `python` interpreter (Python 3.11 or newer). Prepare the checkout and
its example dependencies first. Diplodocus loads the selected checkout, verifies
the module's source path, and starts a fresh process per API document. Examples
within one document share the defining module's globals. The standard library
`doctest` runner checks expected output and exceptions, supports comparison
directives, and records explicit `+SKIP` outcomes. Output mismatches and unexpected
errors prevent publication. Ordinary code fences remain illustrative.

## R

R extraction combines native checkout exports, formals, and S3 registrations
with `DESCRIPTION`, `NAMESPACE`, source attribution, and Rd documentation.
Packages with roxygen metadata regenerate Rd and namespace metadata during
normal commands. Select `r: {documentation: rd}` for maintained Rd or
`r: {documentation: roxygen2}` to require generation. See the
[R workflow](extraction/r.md#roxygen2-or-maintained-rd) for options, custom
roclets, supported versions, and checkout writes.
`check` loads the package for the same API discovery as other commands, without
executing documentation examples. `extract`, `build`, and `serve` execute Rd
examples as a required step.
R Markdown vignettes are also discovered and executed; see
[authored articles](authoring.md).

Prepare a working checkout with R, `pkgload`, `jsonlite`, `evaluate`, the package dependencies,
and the dependencies used by its examples. Compile native extensions beforehand;
Diplodocus never compiles or installs the package. Each help topic runs once in a
fresh R process, including topics shared by several declarations. Expressions
within a topic share state and a graphics device. The package loads from the
configured checkout, and extraction verifies its namespace path and version.

`\dontrun` regions remain explicitly illustrative. `\donttest` regions execute.
False `if` conditions without an `else`, including `interactive()` and platform
checks, record a skip reason. Conditions run once. Missing dependencies requested
through `require()` or `requireNamespace()` cause an error rather than a skip.
Normal R error handling such as `tryCatch()` remains available to examples.

Results, messages, and warnings render as literal text, and recorded plots become
validated PNG assets. Snapshots retain executed expressions, illustrative regions,
skip reasons, the Rd source fingerprint, R and package versions, and loaded
namespace versions. Each extraction executes examples afresh; the QMD cache does
not cover Rd examples. Generation uses the completed snapshot without R or the
checkout. Errors, missing prerequisites, timeouts, invalid figures, and cleanup
failures prevent publication and preserve the previous snapshot and site.

Shared help topics retain all documented usages and arguments on each
declaration's page. Topic aliases resolve to a primary declaration, while
method aliases resolve to their own pages. Links between declarations and
methods grouped by S3 class make the complete topic navigable.

R reference pages use the Rd title as their heading and show the description
before usage. URLs use readable API names, or the topic name for a shared
topic's primary declaration. The reference overview lists each topic with its
title and introductory summary. Code blocks have syntax highlighting and copy
buttons. Usage appears once, including the complete shared topic's signatures.
Source links point to the recorded R and Rd files when the repository has a
revision and a GitHub URL or a supported `source-link-template`. These links
remain available when generating from a snapshot without the checkout.

Rd content supports labeled local and package-qualified help links, equations,
aligned tables, custom sections, named return entries, HTML and platform
conditionals, and DOI links. Equations render natively with `katex-rs` and bundled
fonts, so they work with JavaScript disabled. External help links use installed
help aliases to select rdrr.io destinations; snapshots retain the results so
generation needs neither R nor installed help databases.

Dataset topics marked `\docType{data}` create documented data objects without
requiring source bindings or exports. Their usage lists bare object names, and
their Format and Source sections retain structured prose, lists, and links.

Documented constants retain literal values and assignment aliases from maintained
source bindings. Their usage lists bare object names. Standalone help topics
named `*_deprecated` retain prose and aliases without requiring a function or
inventing a callable signature. Nested Rd lists and prose between described
entries retain their content and order.

Standard S3 generics from default R packages resolve without explicit imports.
R must be available on `PATH`. Native discovery loads the checkout and its
dependencies; supplemental import analysis uses installed metadata. Documented helpers
receive native signatures without requiring exports. Topics marked
`\keyword{internal}` have addressable pages but stay out of navigation and search.
See the R extraction contract below for discovery and import limits.

### Package landing pages

Every package receives a [standard landing page](authoring.md#package-landing-pages).
Diplodocus uses an authored package index, a configured `overview` file, or the
package-root `README.md`, in that order. Without those sources, package metadata
supplies an introduction when available. The compact information block shows
available details from DESCRIPTION, pyproject.toml, Project.toml, or Cargo
metadata. R overviews also link to available release notes, authors and citation
information, licenses, and community guidelines.

Release notes use `NEWS.md`, then `NEWS.Rd`, then plain `NEWS`. Licenses include
the DESCRIPTION declaration, its local `file` references, and conventional
`LICENSE`, `LICENSE.md`, `LICENCE`, `LICENCE.md`, `LICENSE-MIT`, `LICENSE-APACHE`,
`COPYING`, and `COPYING.md` files. Contribution guidelines
and a code of conduct use `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `CONDUCT.md`, preferring
package files over files at the repository root. Missing optional files do not
create empty pages. A missing file explicitly named by License is an error.

Extraction evaluates `Authors@R` and `inst/CITATION` with native R helpers. When
CITATION is absent, R generates a citation from DESCRIPTION. Author supplies a
fallback when Authors@R is absent. R also converts NEWS.Rd to readable text. These
operations use the checkout's files and supplied environment, and do not install
the documented package. Native errors and timeouts prevent publication. `check`
validates source syntax and links without evaluating this information.

An explicitly authored page at the package root or a supporting page's route
takes precedence. Diplodocus resolves these overrides before parsing the
automatically discovered documents, so replaced content does not produce syntax
diagnostics. Links to the original files resolve to the authored replacement.
Files explicitly included by authored collections still receive diagnostics and
are not duplicated automatically. README links, heading anchors, and local
images use the normal reference and asset pipeline. Snapshots retain the
metadata, native results, documents, and assets so `generate` works without the
checkout or R.
README.Rmd rendering remains outside this workflow.

Automatically discovered package pages can also link to existing repository
files outside the declared content, such as `spec/README.md`, `TRUST.md`, and
`OPERATIONS.md` in a root contributor guide. Declared pages and their source
aliases resolve to site pages first. Other local documents and directories use
a repository URL, as do files outside package and content asset boundaries.
This fallback requires a [repository URL or source-link template](configuration.md)
and a declared or observed revision. Missing targets, invalid site anchors,
and paths that leave the source repository remain errors, including symlinks
that leave and reenter it. Diplodocus checks the target's existence and type
without parsing it, reading its contents, or including it in the site.
Fragments on repository links pass to the host without local anchor validation.
Local images still require asset validation; authored HTTP and HTTPS images
retain their external URLs. Explicitly authored pages, including package
overrides and R Markdown articles, keep the usual link rules.

Source parsers retain supported supplemental evidence, while native discovery
handles supported generated bindings. Unsupported Rd markup
stays visible with a diagnostic. For exact parser and identity rules, see the
[Python extraction
contract](https://github.com/jolars/diplodocus/blob/main/docs/ir/python-extraction.md)
or [R extraction
contract](https://github.com/jolars/diplodocus/blob/main/docs/ir/r-extraction.md)
in the source repository.

## Julia

Prepare Julia 1.10 through 1.13 and the checkout's project dependencies. Set
`ecosystem: "julia"`, `metadata-path: "Project.toml"`, and an
`extractor: "julia"` target pointing at `src/MyPackage.jl`.

Diplodocus loads the verified checkout to discover public bindings, documented
private declarations, aliases, and methods. Julia's documentation system
supplies attached docstrings, including documentation created by macros.
Fatou preserves authored signatures and source ranges where it can match them
to the loaded API. Explicit `julia.extensions` entries contribute methods
from source, including when optional dependencies are unavailable.

`check` loads the checkout with document examples kept inert. Extraction
commands verify `jldoctest` blocks before publication. `generate` needs only
the snapshot. See the [Julia guide](extraction/julia.md) for configuration,
doctest syntax, and cache behavior.