Skip to content

docs: fix bugs, wire orphaned pages into nav, refresh compiler and STL docs #129

@steven-varga

Description

@steven-varga

Context

Paige audited docs/ and found a thin nav (4 published pages out of ~12 docs files), several orphaned architecture and example sub-pages, and a handful of content bugs. John, Sally, and Winston weighed in on scope and information architecture.

Immediate Bug Fixes

  • docs/index.md — duplicate word: "With With LLVM-based" (line 6)
  • docs/compiler.md — stale LLVM version reference (7.0.0); currently supported versions are Clang/LLVM 14, 15, 17 (per h5cpp-compiler CI matrix)
  • docs/compiler.md — broken Doxygen-style @ref link_h5cpp_install link; replace with valid MkDocs-relative link

Nav Wiring (publish what already exists)

Wire the following orphaned files into mkdocs.yml:

  • architecture-types.md → under Architecture
  • architecture-integration.md → under Architecture
  • architecture-parallelism.md → under Architecture
  • compiler.md → top-level nav entry
  • examples/attributes.md, examples/datasets.md, examples/groups.md, examples/container.md, examples/sparse-matrix.md → under Examples

architecture.md (top-level monolith) intentionally excluded until the type-engine refactor (branches 89, 92, 114) settles — per Winston.

Content Work

  • docs/stl.md — rewrite from scratch; currently rough notes with typos and placeholder text ("code: 6487")
  • docs/compiler.md — refresh prose to match current LLVM support and link to vargalabs/h5cpp-compiler

Information Architecture (Sally + John)

Target nav structure reflecting three user personas (evaluator, integrator, deep diver):

Overview | Design | Architecture | Type System | I/O Operations | Compiler Tool | Examples

Sally's recommendation: surface the examples/ sub-pages as real nav children, not a single flat page.

Out of Scope

  • New content for architecture.md (blocked on type-engine refactor)
  • Any changes to the MkDocs theme, CSS, or JS

Refs: #128 (README badge PR, same branch candidate)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions