Skip to content

docs: update for Documenter 1.x, surface missing docstrings, add POMDPs.jl page#60

Open
jamgochiana wants to merge 4 commits into
arec/pomdps-interfacefrom
arec/docs-build-fix
Open

docs: update for Documenter 1.x, surface missing docstrings, add POMDPs.jl page#60
jamgochiana wants to merge 4 commits into
arec/pomdps-interfacefrom
arec/docs-build-fix

Conversation

@jamgochiana

Copy link
Copy Markdown
Collaborator

Four commits that bring the documentation up to date:

build(docs): update Documenter API for 1.x compat — replaces format = :html (Documenter 0.x) with format = Documenter.HTML() (Documenter 1.x). The :html form raises Cannot convert Symbol to Documenter.Writer under current Documenter.

docs: surface missing docstrings, resolve duplicate @docs, fix example links — surfaces 6 previously-undocumented public symbols (AbstractFilter, DynamicsModel, ObservationModel, unscented_transform, unscented_transform_inverse, MvNormalPDF) by adding them to the appropriate @docs blocks. Disambiguates duplicate @docs references (the bare GaussianFilters.update/predict/measure references on both kalman.md and gmphd.md were pulling in every method and producing duplicate entries — now method-signature-qualified per page). Updates Example links from notebooks/*.ipynb to examples/*.jl. docs/Project.toml gains a [sources] path entry so docs build against the in-tree source.

docs(kalman): document pomdps_updater and link POMDPs.jl examples — initial integration mention in kalman.md (later moved out by the next commit).

docs: promote POMDPs.jl integration to its own page — moves the POMDPs content out of kalman.md into a new docs/src/pomdps.md under a new Integrations section. Adds a quick-start code snippet, documents direct dispatch vs the pomdps_updater wrapper, and shows initializing a belief from an MvNormal.

Verified locally — docs build cleanly with no missing_docs or docs_block errors.

- Replace 'format = :html' with 'format = Documenter.HTML()' — the
  Symbol-based format API was Documenter 0.x and is unsupported in
  Documenter 1.x (raises 'Cannot convert Symbol to Documenter.Writer').
- Add 'warnonly = [:docs_block, :missing_docs]' so existing
  duplicate-docs / missing-docs issues in the .md sources surface as
  warnings instead of build-blocking errors. Cleaning up those
  individual doc-source issues is out of scope here.

Verified locally with: julia --project=docs docs/make.jl
…e links

Resolve the docs-build issues that were previously masked by warnonly:

Surface 6 previously-undocumented symbols whose docstrings existed in
src/ but were not referenced from any .md page:
- AbstractFilter, DynamicsModel, ObservationModel (now in kalman.md
  intro / 'Building a Filter')
- unscented_transform, unscented_transform_inverse (kalman.md UKF area)
- MvNormalPDF (gmphd.md utilities)

Disambiguate duplicate @docs blocks. The bare GaussianFilters.update /
predict / measure references appeared on both kalman.md and gmphd.md,
each pulling in every method of those generics and producing duplicate
entries. Replace with method-signature-qualified references on each
page so kalman.md documents the Kalman-class methods and gmphd.md
documents the PHDFilter methods.

Update the 'Examples' sections on both pages to point at examples/*.jl
instead of the removed notebooks/*.ipynb (carryover fix from #49).

docs/Project.toml: add GaussianFilters as a dep with a [sources] path
entry so the docs build against the in-tree source (previously docs
relied on the registered version being available).

Remove the warnonly band-aid added earlier in this layer — the build
now passes cleanly with no missing_docs or docs_block errors.
Surface the new pomdps_updater function added in the previous layer and
add the two POMDPs-related examples (pomdps_integration, pendulum_ekf_ilqr)
to the kalman.md examples list. Keeps the docs build clean (no
missing_docs warnings).
Move the POMDPs section out of kalman.md and into a new top-level
Integrations -> POMDPs.jl Integration page (docs/src/pomdps.md). Add
a quick-start code snippet showing the three-step pomdps_updater
usage and document the direct-dispatch path for callers that don't
need the full POMDPs.simulate machinery. Also document the
initialize_belief-from-MvNormal pattern with a small example.

Add a new 'Integrations' section to the pages tree in make.jl.

kalman.md now contains only a one-line cross-reference to the new
page.
@jamgochiana jamgochiana force-pushed the arec/docs-build-fix branch from 0c70816 to f020372 Compare May 27, 2026 20:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant