docs: clean up quarto setup and move docs into doc/ folder

doc/.gitignore

@@ -0,0 +1,7 @@
+/*.html
+/.quarto/
+**/*.quarto_ipynb
+/_freeze/
+/_site/
+/*_files/libs/
+/quarto/

doc/README.md

@@ -0,0 +1,36 @@
+# HPI docs
+
+
+- [Docs](#docs)
+- [Legacy (org, being migrated)](#legacy-org-being-migrated)
+
+Render all documentation with `tox -e quarto`. For live browser preview,
+run `uv run --only-group quarto quarto preview doc --profile preview`
+from the repository root.
+
+With `freeze: auto`, Quarto only detects changes to `.qmd` files. After
+editing `quarto_helpers.py`, run `tox -e quarto -- --execute` or delete
+`_freeze/` to re-execute the docs that import it.
+
+# Docs
+
+User guides:
+
+- [Configuring modules](configuring_modules.md)
+- [Querying HPI](QUERY.md)
+- [Denylists](DENYLIST.md)
+
+Architecture decisions:
+
+- [Configuration requirements](configuration_requirements.md)
+
+# Legacy (org, being migrated)
+
+- [CONFIGURING](CONFIGURING.org)
+- [CONTRIBUTING](CONTRIBUTING.org)
+- [DESIGN](DESIGN.org)
+- [DEVELOPMENT](DEVELOPMENT.org)
+- [MODULES](MODULES.org)
+- [MODULE_DESIGN](MODULE_DESIGN.org)
+- [OVERLAYS](OVERLAYS.org)
+- [SETUP](SETUP.org)

doc/README.qmd

@@ -0,0 +1,32 @@
+---
+title: "HPI docs"
+---
+
+Render all documentation with `tox -e quarto`.
+For live browser preview, run `uv run --only-group quarto quarto preview doc --profile preview` from the repository root.
+
+With `freeze: auto`, Quarto only detects changes to `.qmd` files.
+After editing `quarto_helpers.py`, run `tox -e quarto -- --execute` or delete `_freeze/` to re-execute the docs that import it.
+
+# Docs
+
+User guides:
+
+- [Configuring modules](configuring_modules.md)
+- [Querying HPI](QUERY.md)
+- [Denylists](DENYLIST.md)
+
+Architecture decisions:
+
+- [Configuration requirements](configuration_requirements.md)
+
+# Legacy (org, being migrated)
+
+- [CONFIGURING](CONFIGURING.org)
+- [CONTRIBUTING](CONTRIBUTING.org)
+- [DESIGN](DESIGN.org)
+- [DEVELOPMENT](DEVELOPMENT.org)
+- [MODULES](MODULES.org)
+- [MODULE_DESIGN](MODULE_DESIGN.org)
+- [OVERLAYS](OVERLAYS.org)
+- [SETUP](SETUP.org)

doc/_quarto-preview.yml

@@ -0,0 +1,5 @@
+# Website mode is only for project-wide live preview and qmd-to-html link resolution.
+project:
+  type: website
+
+format: html

doc/quarto/_quarto.yml → doc/_quarto.yml

@@ -4,14 +4,12 @@ project:
     - "*.qmd"  # otherwise picks up .md for some reason??
     - "README.qmd"  # for whatever reason quarto excludes it by default
 format:
-  gfm:
-    toc: true
-    toc-depth: 3
-  html:
-    toc: true
-    toc-depth: 3
-    anchor-sections: true
-    # code-fold: true
+  gfm: default
+  html: default
+toc: true
+toc-depth: 3
+anchor-sections: true
+# code-fold: true
 execute:
   freeze: auto    # re-render only when source changes
 

doc/quarto/configuration_requirements.md → doc/configuration_requirements.md

@@ -22,8 +22,7 @@
 
 This doc describes the technical decisions behind HPI configuration
 system. It’s more of a ‘design doc’ rather than usage guide. If you just
-want to know how to set up HPI or configure it, see
-[SETUP](../SETUP.org).
+want to know how to set up HPI or configure it, see [SETUP](SETUP.org).
 
 I feel like it’s good to keep the rationales in the documentation, but
 happy to [discuss](https://github.com/karlicoss/HPI/issues/46) it here.

doc/quarto/configuration_requirements.qmd → doc/configuration_requirements.qmd

@@ -12,26 +12,12 @@ format:
 
 ```{python}
 #| echo: false
-from pathlib import Path
-import jedi
-
-src_dir = Path.cwd().absolute().parent.parent / 'src'
-assert src_dir.exists(), src_dir
-
-project = jedi.Project(src_dir)
-
-def github_link(name: str) -> str:
-    completions = list(project.complete_search(name, all_scopes=True))
-    assert len(completions) == 1, f"Expected one completion for {name}, got {completions}"
-    [c] = completions
-    [c] = c.goto()
-    rpath = Path(c.module_path).relative_to(src_dir)
-    return f"https://github.com/karlicoss/HPI/blob/master/src/{rpath}#L{c.line}"
+from quarto_helpers import github_link
 ```
 
 This doc describes the technical decisions behind HPI configuration system.
 It's more of a 'design doc' rather than usage guide.
-If you just want to know how to set up HPI or configure it, see [SETUP](../SETUP.org).
+If you just want to know how to set up HPI or configure it, see [SETUP](SETUP.org).
 
 I feel like it's good to keep the rationales in the documentation,
 but happy to [discuss](https://github.com/karlicoss/HPI/issues/46) it here.

doc/quarto/configuring_modules.md → doc/configuring_modules.md

@@ -144,7 +144,7 @@ Cons:
   instantiate the config on first use (TODO link to it later).
 
 See more about this approach
-[here](https://github.com/karlicoss/HPI/blob/master/src/my/core/docs/test_configuration.py#L384).
+[here](https://github.com/karlicoss/HPI/blob/master/src/my/core/docs/test_configuration.py#L386).
 
 # Other options
 

doc/quarto/configuring_modules.qmd → doc/configuring_modules.qmd

@@ -9,21 +9,7 @@ format:
 
 ```{python}
 #| echo: false
-from pathlib import Path
-import jedi
-
-src_dir = Path.cwd().absolute().parent.parent / 'src'
-assert src_dir.exists(), src_dir
-
-project = jedi.Project(src_dir)
-
-def github_link(name: str) -> str:
-    completions = list(project.complete_search(name, all_scopes=True))
-    assert len(completions) == 1, f"Expected one completion for {name}, got {completions}"
-    [c] = completions
-    [c] = c.goto()
-    rpath = Path(c.module_path).relative_to(src_dir)
-    return f"https://github.com/karlicoss/HPI/blob/master/src/{rpath}#L{c.line}"
+from quarto_helpers import github_link
 ```
 
 
@@ -152,4 +138,3 @@ Many actual HPI modules still have different implementations for historic reason
 If you're interested to dig more, see [test_configuration](`{python} github_link("my.core.docs.test_configuration")`) that covers various approaches.
 
 However, we've found that the property-based approach described above has the fewest quirks, so we recommend it going forward.
-

doc/index.qmd

@@ -0,0 +1,10 @@
+---
+title: "HPI docs"
+format: html
+---
+
+<!-- This file only provides the index Quarto requires for project-wide live preview. -->
+
+<meta http-equiv="refresh" content="0; url=README.html">
+
+[Open the documentation index](README.html).

doc/quarto_helpers.py

@@ -0,0 +1,24 @@
+import tomllib
+from pathlib import Path
+
+import jedi
+
+REPO = Path(__file__).parent.parent
+SRC = REPO / "src"
+
+with (REPO / "pyproject.toml").open("rb") as fo:
+    pyproject = tomllib.load(fo)
+GITHUB = pyproject["project"]["urls"]["Homepage"]
+assert isinstance(GITHUB, str), GITHUB
+assert GITHUB.startswith("https://github.com/"), GITHUB
+
+project = jedi.Project(SRC)
+
+
+def github_link(name: str) -> str:
+    completions = list(project.complete_search(name, all_scopes=True))
+    assert len(completions) == 1, f"Expected one completion for {name}, got {completions}"
+    [c] = completions
+    [c] = c.goto()
+    rpath = Path(c.module_path).relative_to(SRC)
+    return f"{GITHUB}/blob/master/src/{rpath}#L{c.line}"