Skip to content

Phase 2a — Fix misplacements, move Reference out of Concepts, delete orphan dirs #2028

@mesejo

Description

@mesejo

Part of #2023. Prereq: Phase 1 complete (#2026, #2027).

1. Move introduction.qmd to Concepts

docs/getting_started/introduction.qmd is Explanation ("what is Xorq, why it
exists") with no hands-on steps. Getting Started should be purely tutorial.

  • Move -> docs/concepts/understanding_xorq/what_is_xorq.qmd.
  • Set title "What is Xorq?"; update _quarto.yml (remove from
    getting-started sidebar, add to concepts).
  • Add a short "What is Xorq?" block to docs/index.qmd linking to the new
    location (search-engine landers).

2. Verify installation.qmd move

Done in Phase 1a. Confirm it happened; if Phase 1 was skipped, move
docs/getting_started/installation.qmd -> docs/how_to/install_xorq.qmd and
update the sidebar.

3. Move Reference docs out of Concepts

Two concepts/ files are actually Reference:

  • concepts/understanding_xorq/expression_format.qmd ->
    reference/expression_format.qmd (YAML format spec).
  • concepts/core_concepts/user_defined_exchange_functions.qmd ->
    reference/user_defined_exchange_functions.qmd (UDXF API contract).
  • Update _quarto.yml reference sidebar + inbound links.
  • If concepts/core_concepts/ is now empty (after Phase 1b removed the
    caching-internals page), delete the directory.

4. Unify the reference hierarchy

Three reference locations: reference/ (auto-gen), api_reference/backends/,
api_reference/cli/.

  • In reference/index.qmd add a "What's here" intro distinguishing the three.
  • Add caching_classes.qmd, expression_format.qmd,
    user_defined_exchange_functions.qmd to the reference sidebar.
  • Do not merge api_reference/ into reference/ — just link them clearly
    from the landing page.

5. Delete orphaned docs/core_concepts/ root dir

A root-level docs/core_concepts/ exists alongside docs/concepts/core_concepts/.

  • If it holds only stale artifacts (no .qmd/.md), remove it.
  • If it has .qmd files, check for duplication, merge if needed, then delete.

6. Consolidate style dirs

docs/style/ and docs/styles/ both exist.

  • Find which is referenced (_quarto.yml / styles.css); delete the other.

Done when

  • getting_started/ is tutorial-only (no introduction, no installation).
  • what_is_xorq.qmd exists and is linked.
  • The two moved Reference files live under reference/.
  • Orphan core_concepts/ root dir gone; one style dir remains.
  • quarto render passes, no broken links.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions