docs: add many pages to get started

Author: machow

docs/_quarto.yml

@@ -39,24 +39,25 @@ website:
       align: left
       contents:
         - get-started/overview.qmd
-        - section: "Basics"
+        - section: "Basic Use"
           contents:
             - get-started/basic-docs.qmd
+            - get-started/basic-building.qmd
             - get-started/crossrefs.qmd
             - get-started/interlinks.qmd
             - get-started/sidebar.qmd
-            - get-started/extending.qmd
             - get-started/advanced-layouts.qmd
+            - get-started/extending.qmd
 
-        - section: "Advanced"
+        - section: "Programming"
           contents:
+            - get-started/dev-big-picture.qmd
+            - get-started/dev-prepare.qmd
             - get-started/docstrings.qmd
             - get-started/renderers.qmd
-            - get-started/building.qmd
-            - get-started/dev-blueprints.qmd
         - section: "Extra Topics"
           contents:
-            - get-started/architecture.qmd
+            - get-started/extra-build-sequence.qmd
 
 
 format:
@@ -154,6 +155,7 @@ quartodoc:
             - layout.DocClass
             - layout.Link
             - layout.Item
+            - layout.ChoicesChildren
     - title: "Data models: AST patches"
       desc: |
         Most of the classes for representing python objects live

docs/examples/index.qmd

@@ -2,13 +2,12 @@
 | ----- | ------ | ------ |
 | [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. |
-| [shiny] | [github][shiny-code] | The shiny docs translated to quartodoc, using a custom renderer. |
+| [shiny] | private repository | The shiny docs translated to quartodoc, using a custom renderer. |
 
 : {tbl-colwidths="[20, 20, 60]"}
 
 [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
-[shiny]: /examples/shiny/reference
-[shiny-code]: https://github.com/machow/quartodoc/tree/main/examples/shiny
+[shiny]: https://shiny.rstudio.com/py/api/

docs/get-started/advanced-layouts.qmd

@@ -0,0 +1,14 @@
+---
+title: Advanced layouts
+jupyter:
+  kernelspec:
+    display_name: Python 3 (ipykernel)
+    language: python
+    name: python3
+---
+
+## Pages
+
+## Children options
+
+## 

docs/get-started/basic-building.qmd

@@ -0,0 +1,20 @@
+---
+title: Building and debugging docs
+jupyter:
+  kernelspec:
+    display_name: Python 3 (ipykernel)
+    language: python
+    name: python3
+---
+
+Basic commands:
+
+* quartodoc build --verbose
+* quartodoc interlinks
+* quarto preview
+
+Extra
+
+* note the write only on change option
+* if in trouble, point to advanced section for loading things in python
+* what if my docstring looks weird? (style vs renderer etc..)

docs/get-started/basic-docs.qmd

@@ -7,13 +7,13 @@ jupyter:
     name: python3
 ---
 
-## Adding configuration
+## Site configuration
 
 quartodoc is configured by adding a `quartodoc` section to your `_quarto.yml`:
 
 ```yaml
 quartodoc:
-  style: single-page
+  style: pkgdown
   dir: reference
   package: quartodoc
   sections:
@@ -24,7 +24,7 @@ quartodoc:
         - preview
 ```
 
-## Top-level options
+### Top-level options
 
 The `quartodoc` section takes a `style` field, specifying which [](`quartodoc.Builder`)
 to use (currently "pkgdown" or "single-page"; see [Examples](/examples/)).
@@ -42,41 +42,104 @@ doc_params = [entry for entry in doc_parts if entry.kind.name == "parameters"][0
 print(renderer.render(doc_params))
 ```
 
-## Section options
+### 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 |
+It requires three pieces of configuration:
 
+* title: a title for the section
+* desc: a description for the section
+* contents: a list of functions to document
 
-## Looking up functions
+## Content configuration
 
-Finding functions to document involves two pieces of configuration:
+Individual content entries (e.g. a function to be documented) can also be customized.
+For example, if you are documenting a python class, you may want to include or exclude
+documentation on specific methods on that class.
+
+Specify content options by setting `name: <content name>`, along with any additional options.
+
+For example, below is a piece of content, MdRenderer, specified without options.
+
+```yaml
+contents:
+  - MdRenderer
+```
+
+We set it to only document its render method, by setting `name: MdRenderer` followed by the
+`members` option.
+
+```yaml
+contents:
+  - name: MdRenderer
+    members:
+      - render
+```
+
+TODO: kinds of content, link to advanced layouts
+
+## Looking up objects
+
+Finding python objects to document involves two pieces of configuration:
 
 * the package name.
-* a list of functions for content.
+* a list of objects for content.
+
+Note that quartodoc can look up anything---whether functions, modules, classes, attributes, or methods.
 
 ```yaml
 quartodoc:
   package: quartodoc
   sections:
-    - contents:
-        # top-level function: quartodoc.get_object
-        - get_object
+    - title: Some section
+      desc: ""
+      contents:
+        - get_object        # function: quartodoc.get_object
+        - ast.preview       # submodule func: quartodoc.ast.preview
+        - MdRenderer        # class: quartodoc.MdRenderer
+        - MdRenderer.render # method: quartodoc.MDRenderer.render
+        - renderers         # module: quartodoc.renderers
+```
+
+The functions listed in `contents` are assumed to be imported from the package.
+
+## Module and class members
+
+Documentation for modules and classes can automatically include their members (e.g. class methods and attributes; everything defined inside a module).
 
-        # top-level class: quartodoc.MdRenderer
-        - MdRenderer
+There are four styles for presenting child members:
+
+```{python}
+#| echo: false
+#| output: asis
+
+# print out the attributes table of ChoicesChildren 
+# this is overkill, but maybe a nice case of dogfooding
+from quartodoc import get_object, MdRenderer
+from quartodoc.builder.utils import extract_type
+from griffe.docstrings.dataclasses import DocstringSectionAttributes
 
-        # submodule function: quartodoc.ast.preview
-        - ast.preview
+renderer = MdRenderer()
+choices = get_object("quartodoc.layout.ChoicesChildren")
+res = extract_type(DocstringSectionAttributes, choices.docstring.parsed)[0]
+
+print(renderer.render(res))
 ```
 
-The functions listed in `contents` are assumed to be imported from the package.
+You can specify a style by setting the `children` option in the config:
 
-### Class methods
+```yaml
+quartodoc:
+  package: quartodoc
+  sections:
+    - title: Some section
+      desc: ""
+      contents:
 
-Currently, quartodoc can't look up class methods. (Though this would be quick to implement!).
+        # set the children option, so that methods get documented
+        # on separate pages. MdRenderer's docs will include a summary
+        # table that links to each page.
+        - name: quartodoc.MdRenderer
+          children: separate
+```