dxkb-docs

Documentation site for the dxkb web application. This is a Sphinx project (Markdown via MyST) that builds to static HTML, published at https://www.dxkb.org/docs/.

It is the direct counterpart to BV-BRC-Docs — the service quick-reference pages here were adapted from that project and rebranded for dxkb.

---

Why this repo exists — the service info dialogs

Every service page in dxkb-web has an ⓘ (info) icon in its title that opens an Overview dialog describing the service. That content is not stored in dxkb-web. At runtime, the app fetches an HTML page from this docs site and pulls one section out of it.

The relevant code lives in dxkb-web at public/js/p3/widget/app/AppBase.js, method gethelp():

1. It fetches docsServiceURL + applicationHelp — e.g. https://www.dxkb.org/docs/ + quick_references/services/genome_annotation_service.html.
2. It finds every .infobutton on the page and reads its name attribute (e.g. overview).
3. It grabs the element in the fetched HTML whose id matches that name and injects it into a dialog. name="overview" → the <section id="overview"> block, name="parameters" → <section id="parameters">, and so on.

The contract this repo must honor: each service .md file needs a ## Overview heading (and optionally ## Parameters, etc.). Sphinx/MyST auto-generates the matching HTML id from the heading text (this is enabled by myst_heading_anchors = 2 in conf.py). So ## Overview becomes <section id="overview">, which is exactly what the info icon looks for.

If the fetch fails (e.g. this site is unreachable), dxkb-web now shows a graceful "Help information is currently unavailable" message instead of a silently dead icon — but the only way to get real content is to publish this site. See "Deployment" below.

---

Repository layout

dxkb-docs/
├── README.md                  ← you are here
├── requirements.txt           ← Python/Sphinx dependencies
└── docroot/
    ├── conf.py                ← Sphinx config (project name, theme, myst_heading_anchors)
    ├── Makefile / make.bat    ← `make html` build entry points
    ├── index.rst              ← master doc; globs in the service pages
    ├── _static/               ← favicon, etc.
    ├── spelling_wordlist.txt  ← allow-list for the spelling checker
    └── quick_references/
        └── services/          ← ONE .md file per service (the actual content)

Build output lands in docroot/_build/html/ and is git-ignored — never commit it.

---

Prerequisites

• Python 3.12+. Sphinx>=8 and myst-parser>=4 floor at 3.10, and pip resolves Sphinx to 9.x, which requires 3.12 — on anything older the pip install below fails outright. (The original pins were inherited from BV-BRC-Docs and no longer build at all: Sphinx 2.2.0 imports jinja2.environmentfilter, which Jinja2 3.x removed. The file pins verified ranges instead; see the comments in it.) CI builds on 3.12 — see .github/workflows/docs-build.yml.
• The enchant native library, required by sphinxcontrib-spelling (apt install libenchant-2-2, or brew install enchant).
• make (standard on macOS/Linux; on Windows use make.bat).

---

Build it locally

# 1. Create and activate a virtual environment (once), from the REPO ROOT --
#    this is where requirements.txt lives, not docroot/
python3 -m venv venv
source venv/bin/activate           # Windows: venv\Scripts\activate

# 2. Install dependencies (once)
pip install -r requirements.txt

# 3. Build the HTML
cd docroot
make html

make html prints ~250 warnings about missing images and unresolved /tutorial/... cross-references — expected, and harmless for the info dialogs (see the note below). Look for build succeeded on the final line.

The site is generated at docroot/_build/html/. Open docroot/_build/html/index.html in a browser to browse it, or verify a single service page:

# should print: id="overview"
grep -o 'id="overview"' _build/html/quick_references/services/genome_annotation_service.html

Note on image warnings: this repo currently contains only the .md text (not the screenshot images), so make html prints "image file not readable" warnings. These are harmless for the info dialogs — the dialog shows only the text of the ## Overview section. If you want the fully-browsable site with screenshots, copy the corresponding images/ folders from BV-BRC-Docs/docroot/quick_references/ (and adjust as needed).

---

Test the dialogs against a local dxkb-web (no deploy needed)

You do not need to deploy this site to test it. Because dxkb-web's PathJoin returns a same-origin URL when docsServiceURL has no http(s):// prefix, and dxkb-web already serves its public/ folder at /public/, you can serve the built docs straight out of dxkb-web:

# From dxkb-docs, after `make html`:
cp -r docroot/_build/html/* /path/to/dxkb-web/public/docs/

# In dxkb-web, edit p3-web.conf (git-ignored, local only) and add:
#   "docsServiceURL": "/public/docs"

# Start dxkb-web (npm start) and click an ⓘ icon, e.g. http://localhost:3000/app/Annotation

public/docs/ and the docsServiceURL override are local test scaffolding only — both are git-ignored in dxkb-web and must never be committed. In production, dxkb-web keeps docsServiceURL pointing at https://www.dxkb.org/docs/ and this site is published there.

---

Deployment (production)

The built static HTML must be served at https://www.dxkb.org/docs/. This mirrors how BV-BRC-Docs is published to bv-brc.org/docs/.

1. cd docroot && make html → produces docroot/_build/html/.
2. Serve/copy that directory's contents to whatever hosts the dxkb.org /docs/ path (nginx static root, object storage + CDN, a CI publish job, etc.).

Currently https://www.dxkb.org/docs/ returns HTTP 403 — nothing is published there yet. Until someone with dxkb.org hosting access serves the build output at /docs/, the info icons in production will show the graceful fallback message. This hosting step is the final unblock and lives outside both repos.

A CI job (e.g. GitHub Action) that runs make html and publishes on merge to the main branch is recommended so content edits don't require a manual build/upload.

---

Editing / adding a service doc

• Each service maps to one file: docroot/quick_references/services/<name>.md. The <name> must match the applicationHelp path set on the corresponding widget in dxkb-web (public/js/p3/widget/app/<Service>.js).
• Always include a ## Overview heading — that's what the info icon shows.
• Match every info button on the service page, not just Overview. Most service forms have three: overview, pdb-selection, and parameters. Check the widget's template (dxkb-web/public/js/p3/widget/app/templates/<Service>.html) for class="... infobutton" and note each button's name — every one needs a matching id or that dialog shows "Help text missing". Note the heading text must slugify to the button name: ## PDB Selection → pdb-selection. A heading like ## Protein Selection yields protein-selection and will not be found.
• Indent nested bullets by 2 spaces, not 8. MyST does not treat an 8-space indent as a sub-list; it silently folds those lines into the parent bullet's text, so the dialog renders them as a run-on paragraph instead of a nested list.
• Keep real tool names and paper citations intact (e.g. RASTtk, PATtyFams, PGFams, and author/journal references). Only brand/UI references (BV-BRC → dxkb, bv-brc.org → dxkb.org) were rebranded.
• After editing, run make html and confirm the section id is generated as expected.

Docs still needing subject-matter review

The following were authored fresh (no BV-BRC equivalent to adapt) and should be reviewed by whoever owns each pipeline:

dxkb-only services (no reference anywhere — highest need):

• stabiliNNator.md (Protein Stability Prediction — proliNNator / disulfiNNate)

The other three dxkb-only pages — frustraMPNN_service.md (FrustraMPNN), stability_prediction_service.md (ThermoMPNN) and structure_sequence_prediction_service.md (ProteinMPNN) — have been replaced with content supplied by the service owners and no longer need review.

BV-BRC services missing from BV-BRC-Docs (drafted from related pages):

• comparative_pathway_service.md
• genomad.md
• mobile_element_detection_service.md