update docs

Author: hamelsmu

docs/get-started/dev-prepare.qmd

@@ -16,7 +16,6 @@ jupyter:
 ```{python}
 from quartodoc import collect, preview
 from quartodoc import MdRenderer
-from quartodoc import layout
 import yaml
 ```
 
@@ -55,7 +54,8 @@ We can see many of the configuration options such as `members`, `name` and `chil
 However, we don't have to start with `yaml` files to create an `Auto` object.  We can also create an `Auto` object with the fully qualified name of any Python object.  For example, we can create an `Auto` object for the `MdRenderer` class like this:
 ```{python}
 from quartodoc import Auto
-auto = Auto(name = "quartodoc.MdRenderer", signature_name = 'short')
+auto = Auto(name = "quartodoc.MdRenderer", 
+            signature_name = 'short')
 print(auto)
 ```
 
@@ -121,59 +121,102 @@ assert docstr_firstln == docstr_firstln_value
 print(docstr_firstln)
 ```
 
-### Layout and Section
+## Layout & Sections
+
+The [](`~quartodoc.layout.Layout`) class stores how you wish to organize your documentation.  For example, you may wish to organize your documentation into sections, where each section contains a title, description, and a list of objects to document.  You can create a layout like this:
 
 ```{python}
+import yaml
+from quartodoc import Builder
+
+cfg = yaml.safe_load("""
+quartodoc:
+  package: quartodoc
+  sections:
+    - title: "Some section"
+      desc: "Some description"
+      contents:
+        - name: MdRenderer
+    - title: "Another section"
+      desc: "Another description"
+      contents:
+        - Auto
+        - blueprint 
+""")
+
+builder = Builder.from_quarto_config(cfg)
+auto_from_yml = builder.layout.sections[0].contents[0]
+preview(builder.layout, max_depth=3)
+```
+
+As you can see, the `Layout`  stores the sections, which are stored in the `sections` attribute.  Each section contains a `title`, `desc`, and `contents` attribute and is stored in a [](`~quartodoc.layout.Section`) class.  
+
+The `contents` attribute is a list of objects to document.  In this case, the first section contains a single object, the `MdRenderer` class, while the second section contains two objects.  You can read more about Section options [here](basic-docs.qmd#section-options).
+
+In addition to building a layout from a yaml file, you can also build a layout in Python by instantiating the `Layout` class like so:
+
+```{python}
+from quartodoc import Auto, layout
+
+auto = Auto(name = "quartodoc.MdRenderer", 
+            signature_name = 'short')
+
 lay = layout.Layout(
     sections = [
-      layout.Section(title = "A section", desc = "A description", contents = [auto])
+      layout.Section(title = "A section", 
+                      desc = "A description", 
+                      contents = [auto])
     ]
 )
 ```
 
-
-:::::: {.columns}
-
-::: {.column}
+We can view the layout by calling the `preview` function:
 
 ```{python}
-# raw layout
-preview(lay, compact=True)
+preview(lay, 
+        max_depth=8, 
+        compact=True)
 ```
 
-:::
-::: {.column}
-
+Recall that the `blueprint` function parses all of the metadata about the Python object.  We can see how a blueprint adds additional data pertaining to `MdRenderer`, that wasn't present in the layout above:
 ```{python}
-bp_layout = blueprint(lay)
-preview(bp_layout, max_depth=5, compact=True)
+bp_layout = blueprint(lay) 
+preview(bp_layout, 
+        max_depth=8, 
+        compact=True)
 ```
 
-:::
 
-::::::
+### Grouping docs on a page
 
-### Grouping docs on single Page
+The Layout also calculates how to split your sections into pages based on the options you set in your yaml configuration.  For example, if you set the `children` option to `separate`, then each object in a section will be placed on its own page.  
 
-### Class members
+Let's see the difference between the `separate` and `embedded` options by creating two `Auto` objects for the `MdRenderer` class, one with `children` set to `separate` and the other with `children` set to `embedded`:
 
 ```{python}
-auto_separate = layout.Auto(name = "quartodoc.MdRenderer", children = "separate")
-auto_embedded = layout.Auto(name = "quartodoc.MdRenderer", children = "embedded")
+auto_sep = layout.Auto(name = "quartodoc.MdRenderer", 
+                       children = "separate")
+auto_emb = layout.Auto(name = "quartodoc.MdRenderer", 
+                       children = "embedded")
 ```
 
+
 :::::: {.columns}
 
 ::: {.column}
 ```{python}
-bp_embedded = blueprint(auto_embedded)
-preview(bp_embedded, max_depth=2)
+bp_emb = blueprint(auto_emb)
+preview(bp_emb, 
+        max_depth=2,
+        compact=True)
 ```
 :::
 ::: {.column}
 ```{python}
-bp_separate = blueprint(auto_separate)
-preview(bp_separate, max_depth=2)
+bp_sep = blueprint(auto_sep)
+preview(bp_sep, 
+        max_depth=2,
+        compact=True)
 ```
 :::