docs: more getting started

Author: machow

docs/_quarto.yml

@@ -47,9 +47,13 @@ website:
             - get-started/crossrefs.qmd
             - get-started/interlinks.qmd
             - get-started/sidebar.qmd
-            - get-started/advanced-layouts.qmd
             - get-started/extending.qmd
 
+        - section: "Docstrings"
+          contents:
+            - get-started/docstring-style.qmd
+            - get-started/docstring-examples.qmd
+
         - section: "Programming"
           contents:
             - get-started/dev-big-picture.qmd

docs/get-started/advanced-layouts.qmd

@@ -11,4 +11,4 @@ jupyter:
 
 ## Children options
 
-## 
+## 

docs/get-started/basic-building.qmd

@@ -29,3 +29,34 @@ quarto preview
 ```bash
 quartodoc build --verbose
 ```
+
+## Speeding up preview
+
+### Rewriting doc files
+
+By default, the `quartodoc build` only re-writes doc pages when it detects
+a change to their content. This helps prevent `quarto preview` from trying
+to re-render every doc page--including those that haven't changed.
+
+###  Selectively building doc pages
+
+Use the filter option with `quartodoc build` to generate a subset of doc pages.
+This is useful when you have a many (e.g. several hundred) doc pages, and want
+to test a change on a single page.
+
+```bash
+quartodoc build --filter 'get_object'
+```
+
+This option also accepts a wildcard pattern, which causes it to build docs for all matching objects.
+
+```bash
+# write the docs for the MdRenderer class, and any of its methods
+# (e.g. MdRenderer.renderer)
+quartodoc build --filter 'MdRenderer*'
+```
+
+:::{.callout-note}
+When using a name with a wildcard, be sure to put it in single quotes!
+Otherwise, your shell may try to "expand it" to match file names.
+:::

docs/get-started/dev-big-picture.qmd

@@ -7,18 +7,27 @@ jupyter:
     name: python3
 ---
 
-* The Builder class loads your quarto config as a layout
-* The ABCs
-  - It contains a bunch of Auto elements, that eventually end up as Page objects.
-* A Renderer handles the output of blueprint into a string
-* Builder methods like `.write_doc_pages()`, or `.write_sidebar()` make the actual site.
+While the "Basic Use" section covered how to configure and build a site with quartodoc, this section focuses on using quartodoc as a python program.
+
+Programming with quartodoc will help with debugging, tinkering, and extending things.
+
+## Overview
+
+When a user runs `quartodoc build`, they 
+
+* Create a [Builder](`quartodoc.Builder`) object, with the quartodoc config loaded as a [layout.Layout](`quartodoc.layout.Layout`).
+* Use [blueprint](`quartodoc.blueprint`) to process the layout into a plan for building the website.
+* Use [collect](`quartodoc.collect`) to get pages to render, and info on where documented objects live.
+
+This page will cover the basics of the Builder and this process.
 
 ## The Builder
 
+The code below shows a Builder object being loaded from a `_quarto.yml` config (loaded as a python dictionary).
+
 ```{python}
 import yaml
 
-from pprint import pprint
 from quartodoc import Builder, preview, blueprint, collect, MdRenderer
 
 cfg = yaml.safe_load("""
@@ -41,33 +50,89 @@ builder
 Note that .from_quarto_config used the `style:` field to decide which Builder to create
 (in this case, PkgdownBuilder).
 
+We can view the config as a [layout.Layout](`quartodoc.layout.Layout`), by looking at the `.layout` attribute.
+
+```{python}
+builder.layout
+```
+
+This can be a bit difficult to read, so quartodoc implements a [preview](`quartodoc.preview`) function, which spaces things out.
+
 ```{python}
 preview(builder.layout)
 ```
 
+Notice the following:
+
+* `preview` represents calls like `Layout()` with a box to the left, and then
+a pipe connecting it to each of its arguments.
+* The content entry `MdRenderer` is represented by an [Auto](`quartodoc.Auto`) class.
+  This specifies a python object to look up and document.
+
+We can follow the path in the preview above, to pull out just the contents piece:
+
 ```{python}
 content = builder.layout.sections[0].contents
 preview(content)
 ```
 
+Next, we'll look at `blueprint()`, which processes the layout, including transforming `Auto` objects into more concrete instructions.
+
 ## From config to blueprint
 
+The code below shows how `blueprint()` transforms the `Auto` entry for `MdRenderer`.
+
 ```{python}
 bp = blueprint(builder.layout)
 bp_contents = bp.sections[0].contents
 preview(bp_contents[0], max_depth=3)
 ```
 
+Notice two key pieces:
+
+* The outermost element is now a [layout.Page](`quartodoc.layout.Page`).
+  The `.path` indicates that the documentation will be on a page called `"MdRenderer"`.
+* The content of the page is a [layout.DocClass](`quartodoc.layout.DocClass).
+  This element holds everything needed to render this doc, including the class signature
+  and parsed docstring.
+
+Importantly, the `.members` attribute specifies how to render the class methods we specified (`.render()` and `.summarize()`).
+
+```{python}
+preview(bp_contents[0].contents[0].members, max_depth=2)
+```
+
+Note that they are also a instances of `Page` (`MemberPage` to be exact).
+Before to building the site, we need to `collect()` all the pages.
+
+
 
 ## Collecting pages and items
 
+The [collect](`quartodoc.collect`) function pulls out two important pieces of information:
+
+* **pages** - each page to be rendered.
+* **items** - information on where each documented object lives in the site.
+
 ```{python}
 pages, items = collect(bp, builder.dir)
 preview(pages, max_depth=3)
 ```
 
+The code below shows a preview of the items.
+
+```{python}
+preview(items, max_depth=2)
+```
+
+Notice that if you wanted to look up `quartodoc.MdRenderer.render`, the first item's `.uri` attribute shows the URL for it, relative to wherever the doc site is hosted.
+
+
 ## Rendering and writing
 
+A `Builder` instantiates a `Renderer` (like [MdRenderer](`quartodoc.MdRenderer`)).
+Use the `.renderer` attribute to access it.
+
 ```{python}
 builder.renderer
 ```
@@ -77,11 +142,9 @@ print(builder.renderer.render(pages[0]))
 
 ```
 
-TODO: note about static analysis, dynamic option.
-
-```{python}
-#| eval: false
-builder.write_doc_pages(pages)
-```
-
+## Writing pages
 
+The builder has a number of methods it uses during build.
+The main method is [.build()](`quartodoc.Builder.build`).
+See the [Builder section of the API](#api-builders) for a list of methods,
+or this [giant build process diagram](/get-started/extra-build-sequence.qmd) for a full breakdown.

docs/get-started/docstring-examples.qmd

@@ -0,0 +1,41 @@
+---
+title: 🚧 Examples
+jupyter:
+  kernelspec:
+    display_name: Python 3 (ipykernel)
+    language: python
+    name: python3
+---
+
+```{python}
+from quartodoc import MdRenderer, preview
+
+renderer = MdRenderer()
+```
+
+## Returns: using type annotation
+
+In order to use the return type annotation of a function, use the following syntax.
+
+```
+Returns
+--------
+:
+    Some description of result
+```
+
+Below is a full example.
+
+```{python}
+def f() -> int:
+    """Some func
+
+    Returns
+    -------
+    :
+        A number
+    """"
+
+```
+
+TODO: need to load as a griffe object somehow.

docs/get-started/docstring-style.qmd

@@ -0,0 +1,13 @@
+---
+title: numpydoc style
+jupyter:
+  kernelspec:
+    display_name: Python 3 (ipykernel)
+    language: python
+    name: python3
+---
+
+quartodoc expects numpydoc style for docstrings.
+See the [numpydoc sections guide][numpydoc] for more information and examples.
+
+[numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html#sections

docs/get-started/extending.qmd

@@ -64,8 +64,8 @@ quartodoc:
     style: _renderer.py
 ```
 
-See the [shiny example docs](https://github.com/machow/quartodoc/tree/main/examples/shiny), which contains a custom renderer.
-
+See the [Rendering docstrings](/get-started/renderers.qmd) page for instructions on
+creating a custom renderer, and the [](`quartodoc.MdRenderer`) docs for more information.
 
 ## Using a custom Builder
 

docs/get-started/extra-build-sequence.qmd

@@ -7,6 +7,9 @@ jupyter:
     name: python3
 ---
 
+This sequence diagram shows the process behind `quartodoc build`.
+See the API docs for [](`~quartodoc.Builder`), [](`~quartodoc.MdRenderer`), and the preperation functions ([](`~quartodoc.Auto`), [](`~quartodoc.blueprint`), [](`~quartodoc.collect`))
+
 ```{mermaid}
 %%| fig-width: 100%
 sequenceDiagram

docs/get-started/renderers.qmd

@@ -129,3 +129,29 @@ Note 3 big pieces:
 * **Tree walking**: `render` methods often call `render` again on sub elements.
 
 
+## Completing the Renderer
+
+While the above example showed a simple example with a `.render` method, a complete renderer will often do two more things:
+
+* Subclass an existing renderer.
+* Also override other methods like `.summarize()`
+
+```{python}
+from quartodoc import MdRenderer
+
+class NewRenderer(MdRenderer):
+    style = "new_renderer"
+
+    @dispatch
+    def render(self, el):
+        print("calling parent method for render")
+        return super().render(el)
+    
+    @dispatch
+    def summarize(self, el):
+        print("calling parent method for summarize")
+        return super().summarize(el)
+```
+
+For a list of methods, see the [](`~quartodoc.MdRenderer`) docs.
+