docs: doc improvements for pr review

Author: machow

docs/get-started/basic-content.qmd

@@ -61,6 +61,8 @@ The functions listed in `contents` are assumed to be imported from the package.
 
 Documentation for modules and classes can automatically include their members (e.g. class methods and attributes; everything defined inside a module).
 
+By default, all attributes and functions (including methods on a class) are documented by embedding them inside the module or class documentation.
+
 There are four styles for presenting child members:
 
 ```{python}
@@ -170,4 +172,20 @@ quartodoc:
 ```
 
 :::
-::::::
+::::::
+
+
+## Dynamic lookup
+
+By default, quartodoc uses static analysis to look up objects.
+This means it gets information about your docstring without actually running your package's code.
+
+This usually works well, but may get the docstring wrong for those created in an extremely dynamic way (e.g. you manually set the `__doc__` attribute on an object).
+
+In this case, you can set the dynamic option on a piece of content.
+
+```yaml
+contents:
+  - name: get_object
+    dynamic: true
+```

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

@@ -72,7 +72,7 @@ a pipe connecting it to each of its arguments.
 We can follow the path in the preview above, to pull out just the contents piece:
 
 ```{python}
-content = builder.layout.sections[0].contents
+content = builder.layout.sections[0].contents[0]
 preview(content)
 ```
 
@@ -84,13 +84,13 @@ The code below shows how `blueprint()` transforms the `Auto` entry for `MdRender
 
 ```{python}
 bp = blueprint(builder.layout)
-bp_contents = bp.sections[0].contents
-preview(bp_contents[0], max_depth=3)
+bp_contents = bp.sections[0].contents[0]
+preview(bp_contents, max_depth=3)
 ```
 
 Notice two key pieces:
 
-* The outermost element is now a [layout.Page](`quartodoc.layout.Page`).
+* The `Auto` 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
@@ -99,7 +99,7 @@ Notice two key pieces:
 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)
+preview(bp_contents.contents[0].members, max_depth=2)
 ```
 
 Note that they are also a instances of `Page` (`MemberPage` to be exact).

docs/get-started/overview.qmd

@@ -9,11 +9,15 @@ jupyter:
     name: python3
 ---
 
-::: {.callout-warning} 
-quartodoc is work in progress!
+::: {.callout-note} 
+quartodoc is used to create the API documentation for [shiny], [siuba], and [vetiver].
+
+It's full-featured and relatively stable, but may see some small changes in the the name of making API documentation a real delight.
+
+If you're interested in using quartodoc for your package's documentation, please open an issue, so we can make sure it does exactly what you want.
 :::
 
-quartodoc let's you quickly generate python package documentation,
+quartodoc lets you quickly generate python package documentation,
 using markdown and [quarto](https://quarto.org).
 It is designed as an alternative to Sphinx.
 
@@ -36,17 +40,16 @@ First, create a `_quarto.yml` file with the following:
 ```yaml
 project:
   type: website
-  resources:
-    - objects.json
 
 quartodoc:
-  style: single-page
-  dir: reference
+  # the name used to import the package
   package: quartodoc
   sections:
     - title: Some functions
       desc: Functions to inspect docstrings.
       contents:
+        # the functions being documented in the package.
+        # you can refer to anything: class methods, modules, etc..
         - get_object
         - preview
 ```
@@ -86,7 +89,7 @@ python -m quartodoc build
 
 ## Looking up objects
 
-Finding Python objects to document involves two pieces of configuration:
+Finding python objects to document involves two pieces of configuration:
 
 * the package name.
 * a list of objects for content.
@@ -110,19 +113,6 @@ quartodoc:
 The functions listed in `contents` are assumed to be imported from the package.
 
 
-## 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 (with interlinks filter).
-  - Link to functions within a doc.
-  - Link to functions in other docs.
-  - Generate an inventory file for other docs to link to yours.
-* Generate high-level summaries (with [Builder](/api/#api-builders)).
-  - First line of docstring used as description.
-  - Class doc pages have table of class attributes.
-  - Index pages list function names and descriptions.
-
 ## Example sites
 
 ### Demo sites