tweaks to make docs simpler, more comprehensive

Author: machow

Makefile

@@ -2,6 +2,7 @@ README.md: README.qmd
 	quarto render $<
 
 examples/%/_site: examples/%/_quarto.yml
+	python -m quartodoc $<
 	quarto render $(dir $<)
 
 docs/examples/%: examples/%/_site

docs/_quarto.yml

@@ -74,9 +74,9 @@ website:
       style: floating
       align: left
       contents:
+        - get-started/overview.qmd
         - section: "Basics"
           contents:
-            - get-started/overview.qmd
             - get-started/basic-docs.qmd
             - get-started/crossrefs.qmd
         - section: "Advanced"

docs/get-started/basic-docs.qmd

@@ -1,10 +1,82 @@
 ---
-title: Generating docs
+title: Configuring docs
 jupyter:
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
     name: python3
 ---
 
-Coming soon!
+## Adding configuration
+
+quartodoc is configured by adding a `quartodoc` section to your `_quarto.yml`:
+
+```yaml
+quartodoc:
+  style: single-page
+  dir: reference
+  package: quartodoc
+  sections:
+    - title: Some functions
+      desc: Functions to inspect docstrings.
+      contents:
+        - get_object
+        - preview
+```
+
+## Options
+
+The `quartodoc` section takes a `style` field, specifying which [](`quartodoc.Builder`)
+to use (currently "pkgdown" or "single-page"; see [Examples](/examples/)).
+
+```{python}
+#| echo: false
+#| output: asis
+from quartodoc import get_object, MdRenderer
+
+obj = get_object("quartodoc", "Builder")
+renderer = MdRenderer()
+
+doc_parts = obj.docstring.parsed
+doc_params = [entry for entry in doc_parts if entry.kind.name == "parameters"][0]
+print(renderer.to_md(doc_params))
+```
+
+## Section options
+
+The `sections` field defines which functions to document.
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| title | str | A title for the section |
+| desc | str | A description for the section |
+| contents | list[str] | A list of functions to document |
+
+
+## Looking up functions
+
+Finding functions to document involves two pieces of configuration:
+
+* the package name.
+* a list of functions for content.
+
+```yaml
+quartodoc:
+  package: quartodoc
+  sections:
+    - contents:
+        # top-level function: quartodoc.get_object
+        - get_object
+
+        # top-level class: quartodoc.MdRenderer
+        - MdRenderer
+
+        # submodule function: quartodoc.ast.preview
+        - ast.preview
+```
+
+The functions listed in `contents` are assumed to be imported from the package.
+
+### Class methods
+
+Currently, quartodoc can't look up class methods. (Though this would be quick to implement!).

docs/get-started/overview.qmd

@@ -1,5 +1,7 @@
 ---
 title: Overview
+aliases:
+  - ../index.html
 jupyter:
   kernelspec:
     display_name: Python 3 (ipykernel)
@@ -12,7 +14,8 @@ quartodoc is work in progress!
 :::
 
 quartodoc let's you quickly generate python package documentation,
-using markdown and quarto. It is designed as an alternative to sphinx.
+using markdown and [quarto](https://quarto.org).
+It is designed as an alternative to Sphinx.
 
 ## Installation
 
@@ -25,6 +28,11 @@ python -m pip install git+https://github.com/machow/quartodoc.git
 
 ## Basic use
 
+Getting started with quartodoc takes two steps: configuring a quarto website,
+and generating documentation pages for your library.
+
+First, create a `_quarto.yml` file with the following:
+
 ```yaml
 project:
   type: website
@@ -37,26 +45,50 @@ quartodoc:
   package: quartodoc
   sections:
     - title: Some functions
-      desc: These functions inspect and parse docstrings.
+      desc: Functions to inspect docstrings.
       contents:
         - get_object
         - preview
 ```
 
-## Goals
+Next, run this command to generate your API pages:
+
+```bash
+python -m quartodoc
+```
+
+This should create a `reference/` directory with an `index.qmd` and documentation
+pages for listed functions, like `get_object` and `preview`.
+
+Finally, preview your website with quarto:
+
+```bash
+quarto preview
+```
+
+## Key Features
 
 * Load docstrings (with [griffe](https://github.com/mkdocstrings/griffe))
 * Render docstrings (e.g. with [MdRenderer](/api/#sec-MdRenderer))
 * Enable cross references to function documentation.
   - Link to functions within a doc.
   - Link to functions in other docs.
   - Generate an inventory file for other docs to link to yours.
-* (WIP) Generate high-level summaries.
-  - Class summaries, with methods.
+* Generate high-level summaries.
+  - First line of docstring used as description.
+  - Class doc pages have table of class attributes.
   - Tables of function names and descriptions.
 
-## Different documentation structures
+## Example sites
+
+| style | source | layout |
+| ----- | ------ | ------ |
+| [pkgdown] | [github][pkgdown-code] | Index page with a title and short description for functions listed in each section. Each function gets its own documentation page. |
+| [single-page] | [github][sp-code] | Index page has function documentation embedded on it. |
+
+: {tbl-colwidths="[20, 20, 60]"}
 
-* All functions listed on a single page.
-* Functions split across a few pages (e.g. parsers, renderers).
-* Each function gets its own page.
+[pkgdown]: /examples/pkgdown/reference
+[pkgdown-code]: https://github.com/machow/quartodoc/tree/main/examples/pkgdown
+[single-page]: /examples/single-page/reference
+[sp-code]: https://github.com/machow/quartodoc/tree/main/examples/single-page

docs/get-started/quickstart.qmd

@@ -12,8 +12,8 @@ Fetch a griffe object.
 | `object_name` | str    | A function name.           | required  |
 | `parser`      | str    | A docstring parser to use. | `'numpy'` |
 
-See Also
---------
+### See_Also
+
 get_function: a deprecated function.
 
 ### Examples

docs/index.qmd

@@ -1,8 +1,22 @@
 import click
+import contextlib
+import os
+
+from pathlib import Path
 
 from .autosummary import Builder
 
 
+@contextlib.contextmanager
+def chdir(new_dir):
+    prev = os.getcwd()
+    os.chdir(new_dir)
+    try:
+        yield new_dir
+    finally:
+        os.chdir(prev)
+
+
 @click.command()
 @click.argument("config", default="_quarto.yml")
 @click.option("--dry-run", is_flag=True, default=False)
@@ -12,7 +26,8 @@ def build(config, dry_run):
     if dry_run:
         click.echo(builder.render_index())
     else:
-        builder.build()
+        with chdir(Path(config).parent):
+            builder.build()
 
 
 if __name__ == "__main__":

examples/pkgdown/reference/get_object.qmd

@@ -94,10 +94,10 @@ class Builder:
 
     Parameters
     ----------
-    sections: ConfigSection
-        A list of sections, with items to document.
     package: str
         The name of the package.
+    sections: ConfigSection
+        A list of sections, with items to document.
     version:
         The package version. By default this attempts to look up the current package
         version (TODO).
@@ -141,8 +141,8 @@ def __init_subclass__(cls, **kwargs):
 
     def __init__(
         self,
-        sections: "list[Any]",
         package: str,
+        sections: "list[Any]",
         version: "str | None" = None,
         dir: str = "reference",
         title: str = "Function reference",