Skip to content

interactive-documentation.md

Latest commit

 

History

History
106 lines (83 loc) · 4.77 KB

interactive-documentation.md

File metadata and controls

106 lines (83 loc) · 4.77 KB
Raw

Interactive Documentation

Issue #1635. A browser-based companion to the Markdown docs: full-text search, runnable API examples, embedded playgrounds, and a feedback loop. It lives in interactive/index.html and needs no build step or external dependencies.

Running it

The page loads its search index with fetch, so it must be served over HTTP (opening the file directly from disk disables search).

# 1. (Re)build the search index after changing any docs/**/*.md
python3 scripts/build_docs_search_index.py

# 2. Serve the docs folder
python3 -m http.server 8000 --directory docs

# 3. Open http://localhost:8000/interactive/

Deep links: /interactive/#api, #slice, #hash, #feedback; a search can be pre-filled with ?q=threshold, and the feedback form with ?page=docs/quorum-slice-guide.md#feedback.

Features

1. Documentation search

  • Client-side full-text search across every docs/**/*.md file, split into sections at headings (H1–H4).
  • Results rank heading matches above body matches, highlight the terms, and link to the exact section on GitHub.
  • The index is docs/interactive/search-index.json, generated by scripts/build_docs_search_index.py. Run it with --check to verify the committed index is current.
  • Version switcher (#1642). The Docs version menu in the header lists the versions in versions.json. Picking one rewrites result links to that version's git ref and shows a deprecation / end-of-life banner where relevant; the choice is kept in ?v=. See documentation-versioning.md.

2. Interactive code examples (API playground)

  • Preset requests for the most-used endpoints: health, credential lookup and search, slice listing and verification, batch verification, and share-link creation.
  • Mock mode (default) answers with the documented examples from api-response-examples.md, including validation errors — edit the body (e.g. set expiry_hours to 0) to see them. No server needed.
  • Live mode sends the request to the configured base URL with an optional x-api-key. For a local API server, allow the docs origin: CORS_ALLOWED_ORIGINS=http://localhost:8000.
  • Show as curl turns the current request into a copy-pasteable command (the key is replaced with $QP_API_KEY, never echoed).
  • The API key is held in memory only; it is never written to storage.

3. Embedded playgrounds

  • Quorum slice simulator — add attestors, set weights (1–100) and a threshold, tick who has attested, and see whether quorum is reached. It warns about unreachable thresholds, invalid weights, and single attestors who can meet the threshold alone (see security-best-practices.md). It also emits the matching stellar contract invoke … create_slice command.
  • Metadata hash — computes the SHA-256 of pasted text or a local file with the Web Crypto API (nothing leaves the browser) and emits the matching issue_credential command.

4. Documentation feedback loop

  1. A reader fills in the page, a helpful/partly/no rating, a problem type, and details.
  2. Open GitHub issue saves the entry locally and opens a prefilled issue using the docs-feedback template, which applies the documentation and docs-feedback labels.
  3. Maintainers triage docs-feedback issues weekly:
    • fix small issues directly and close with a link to the commit;
    • label larger gaps good first issue where appropriate;
    • when a page accumulates repeated "unclear" feedback, schedule a rewrite and consider a video tutorial for it.
  4. Readers can see their own past feedback on the same tab (kept in browser storage, last 50 entries).

Nothing is sent anywhere until the reader submits the issue on GitHub.

Maintaining it

When you… Do this
Add, rename, or edit a doc Re-run python3 scripts/build_docs_search_index.py and commit the updated search-index.json.
Change a response shape Update api-response-examples.md and the matching mock in interactive/index.html.
Add a commonly used endpoint Add a preset to PRESETS in interactive/index.html.
Cut or deprecate a docs version Run `python3 scripts/docs_versions.py cut
Change slice rules (weight range, threshold semantics) Update computeSlice() in interactive/index.html.

The page is plain HTML, CSS, and JavaScript with no dependencies. Keep it that way so it works offline and in any static host.