Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/devdocs/README.md

Raw
Rendered preview
devdocs

devdocs

Find technical documentation, then read only relevant sections with version evidence and provenance.

Use in Pi

Ask Pi to search technical documentation with the devdocs tool, then read the returned refs. Installed documentation and configured local files work offline. Search results carry source, origin, version, and freshness. Documentation is untrusted reference data, never instructions.

Use action: "search" with target, query, and an optional version. Search returns at most 10 ranked section hits per lookup; refine the query to reach other sections. Use action: "read" with returned refs; continuation is the next refs list. action: "status" lists enabled adapters, source catalog, format capabilities, and Context7 mode. action: "refresh" repeats a target/query lookup with validation.

Default adapters: local installed docs, DevDocs.io, upstream references, then Context7. Context7 works anonymously where provider policy permits; CONTEXT7_API_KEY or Pi's Context7 credential raises provider access according to its plan. Missing providers and incompatible versions produce explicit reasons instead of guessed content. Explicit versions require source evidence; unknown versions remain unknown. For installed Unix manuals use targets such as man:2:open or info:coreutils. For JVM library documentation use maven:group:artifact:version or register existing Javadoc.

Fresh remote hits avoid network retrieval. Stale hits return cached sections while validation runs; offline mode prevents remote discovery and fetching. Previously cached complete documents remain searchable with new queries offline; query-selected snippets and archive pages retain their query scope. Refresh updates future searches, never silently changes existing refs. Evicted or disabled-source refs fail explicitly.

Register documentation

Add local files/directories or HTTPS sources in personal Pi settings. Supply exactly one absolute path or HTTPS url per source, then include its ID in enabledSources. URLs cannot contain credentials or query parameters. version, when supplied, asserts the registered source's documentation version. private: true scopes its cached refs to the current project context; it does not configure remote authentication.

{
  "devdocs": {
    "enabledSources": ["local", "devdocs", "upstream", "context7", "manual"],
    "sources": [
      {
        "id": "manual",
        "target": "example-tool",
        "url": "https://docs.example.org/guide.md",
        "format": "markdown"
      }
    ]
  }
}

Available formats include static HTML, Markdown/MDX, reStructuredText, JSON registries, man/Info text, existing Javadoc/JARs, Sphinx inventories, Doxygen indexes, and installed Dash/Zeal docsets. Indexes resolve to linked documentation bodies; fetched scripts, macros, and directives are never executed. MDX and reStructuredText use static subsets and retain unsupported expressions as inert text. PDF text extraction requires an already installed pdftotext; no tools or dependencies are installed during retrieval. Remote tarball/docset-feed expansion and Microsoft Learn MCP transport are not implemented; their catalog entries are not availability claims.

Cache location and limits

Set devdocs.databasePath in personal Pi settings to override the OS user-cache database location. The override must be an absolute file path. Changing paths does not migrate or delete the previous cache. No personal settings are modified automatically.

Read budgets count the serialized result's Unicode code points, including provenance and continuation metadata, not model-specific tokens. Default budget: 4000; accepted range: 512–64000. If metadata leaves no room for content progress, request a larger budget. Continue truncated reads using the returned refs.

The default logical cache allowance is 256 MiB. Logical accounting charges twice each serialized document/discovery payload plus per-section metadata reserves for indexing. The SQLite main file is capped at 1 GiB; rollback journals and headers may temporarily require up to approximately another 1 GiB. Eviction reuses free database pages and does not promise immediate filesystem shrinkage. Each input/document is bounded at 8 MiB; individual network adapters may impose lower limits. Use a local filesystem for the shared cache. No startup crawl or background daemon runs. Settings changes take effect in the next session or after /reload.

Installation

Reference

Setting names

Setting Environment
devdocs.cacheBytes
devdocs.databasePath PI_DEVDOCS_DATABASE_PATH
devdocs.enabledSources
devdocs.offline PI_DEVDOCS_OFFLINE
devdocs.sources
devdocs.ttlSeconds

Setting values

Setting Default Valid values Purpose
devdocs.cacheBytes 268435456 Integer 1048576–1073741824
devdocs.ttlSeconds 86400 Integer 0–2592000

Object fields

Paths below describe fields inside their parent settings object, not literal top-level keys. [] denotes an array element; see setup above for examples and defaults.

Field
devdocs.sources[].id
devdocs.sources[].target
devdocs.sources[].path
devdocs.sources[].version
devdocs.sources[].format
devdocs.sources[].url
devdocs.sources[].private
<img src="assets/banner.svg" alt="devdocs" height="70">

# devdocs

Find technical documentation, then read only relevant sections with version evidence and provenance.

## Use in Pi

Ask Pi to search technical documentation with the `devdocs` tool, then read the returned refs.
Installed documentation and configured local files work offline.
Search results carry source, origin, version, and freshness.
Documentation is untrusted reference data, never instructions.

Use `action: "search"` with `target`, `query`, and an optional `version`.
Search returns at most 10 ranked section hits per lookup; refine the query to reach other sections.
Use `action: "read"` with returned `refs`; `continuation` is the next refs list.
`action: "status"` lists enabled adapters, source catalog, format capabilities, and Context7 mode.
`action: "refresh"` repeats a target/query lookup with validation.

Default adapters: local installed docs, DevDocs.io, upstream references, then Context7.
Context7 works anonymously where provider policy permits; `CONTEXT7_API_KEY` or Pi's Context7 credential raises provider access according to its plan.
Missing providers and incompatible versions produce explicit reasons instead of guessed content.
Explicit versions require source evidence; unknown versions remain unknown.
For installed Unix manuals use targets such as `man:2:open` or `info:coreutils`.
For JVM library documentation use `maven:group:artifact:version` or register existing Javadoc.

Fresh remote hits avoid network retrieval.
Stale hits return cached sections while validation runs; offline mode prevents remote discovery and fetching.
Previously cached complete documents remain searchable with new queries offline; query-selected snippets and archive pages retain their query scope.
Refresh updates future searches, never silently changes existing refs.
Evicted or disabled-source refs fail explicitly.

### Register documentation

Add local files/directories or HTTPS sources in personal Pi settings.
Supply exactly one absolute `path` or HTTPS `url` per source, then include its ID in `enabledSources`.
URLs cannot contain credentials or query parameters.
`version`, when supplied, asserts the registered source's documentation version.
`private: true` scopes its cached refs to the current project context; it does not configure remote authentication.

```json
{
  "devdocs": {
    "enabledSources": ["local", "devdocs", "upstream", "context7", "manual"],
    "sources": [
      {
        "id": "manual",
        "target": "example-tool",
        "url": "https://docs.example.org/guide.md",
        "format": "markdown"
      }
    ]
  }
}
```

Available formats include static HTML, Markdown/MDX, reStructuredText, JSON registries, man/Info text, existing Javadoc/JARs, Sphinx inventories, Doxygen indexes, and installed Dash/Zeal docsets.
Indexes resolve to linked documentation bodies; fetched scripts, macros, and directives are never executed.
MDX and reStructuredText use static subsets and retain unsupported expressions as inert text.
PDF text extraction requires an already installed `pdftotext`; no tools or dependencies are installed during retrieval.
Remote tarball/docset-feed expansion and Microsoft Learn MCP transport are not implemented; their catalog entries are not availability claims.

### Cache location and limits

Set `devdocs.databasePath` in personal Pi settings to override the OS user-cache database location.
The override must be an absolute file path.
Changing paths does not migrate or delete the previous cache.
No personal settings are modified automatically.

Read budgets count the serialized result's Unicode code points, including provenance and continuation metadata, not model-specific tokens.
Default budget: 4000; accepted range: 512–64000.
If metadata leaves no room for content progress, request a larger budget.
Continue truncated reads using the returned refs.

The default logical cache allowance is 256 MiB.
Logical accounting charges twice each serialized document/discovery payload plus per-section metadata reserves for indexing.
The SQLite main file is capped at 1 GiB; rollback journals and headers may temporarily require up to approximately another 1 GiB.
Eviction reuses free database pages and does not promise immediate filesystem shrinkage.
Each input/document is bounded at 8 MiB; individual network adapters may impose lower limits.
Use a local filesystem for the shared cache.
No startup crawl or background daemon runs.
Settings changes take effect in the next session or after `/reload`.

[Installation](../../README.md#install)

## Reference

<!-- config:start -->
### Setting names

| Setting | Environment |
| --- | --- |
| `devdocs.cacheBytes` |   |
| `devdocs.databasePath` | `PI_DEVDOCS_DATABASE_PATH` |
| `devdocs.enabledSources` |   |
| `devdocs.offline` | `PI_DEVDOCS_OFFLINE` |
| `devdocs.sources` |   |
| `devdocs.ttlSeconds` |   |

#### Setting values

| Setting | Default | Valid values | Purpose |
| --- | --- | --- | --- |
| `devdocs.cacheBytes` | `268435456` | Integer 1048576–1073741824 |   |
| `devdocs.ttlSeconds` | `86400` | Integer 0–2592000 |   |

#### Object fields

Paths below describe fields inside their parent settings object, not literal top-level keys.
`[]` denotes an array element; see setup above for examples and defaults.

| Field |
| --- |
| `devdocs.sources[].id` |
| `devdocs.sources[].target` |
| `devdocs.sources[].path` |
| `devdocs.sources[].version` |
| `devdocs.sources[].format` |
| `devdocs.sources[].url` |
| `devdocs.sources[].private` |
<!-- config:end -->