docs: more examples, more content config sections

Author: machow

docs/get-started/basic-content.qmd

@@ -20,8 +20,7 @@ contents:
   - MdRenderer
 ```
 
-We set it to only document its render method, by setting `name: MdRenderer` followed by the
-`members` option.
+We set it to only document its render method, by setting `name: MdRenderer` followed by the `members` option.
 
 ```yaml
 contents:
@@ -175,6 +174,51 @@ quartodoc:
 ::::::
 
 
+## Setting default package path
+
+Different levels of configuration let you set the `package` option.
+This controls the package path that quartodoc will try to import control content from.
+
+The example below shows three different places it can be set:
+top-level site config, section config, or in a page element.
+
+```yaml
+# (1) package set on top-level site config
+quartodoc:
+  package: quartodoc
+  sections:
+    - title: ""
+      desc: ""
+      contents:
+        - get_object         # quartodoc.get_object
+    
+    # (2) package set on a section
+    - title: ""
+      desc: ""
+      package: quartodoc.ast
+      contents:
+        - preview            # quartodoc.ast.preview
+
+        # (3) package set on a page
+        - kind: page
+          package: pandas
+          contents:
+            - DataFrame     # pandas.DataFrame
+```
+
+Use `package: null` to unset the package option. This enables you to specify objects using their full name.
+
+```yaml
+quartodoc:
+  package: quartodoc
+  sections:
+    - title: ""
+      desc: ""
+      package: null
+      contents:
+        - quartodoc.get_object
+```
+
 ## Dynamic lookup
 
 By default, quartodoc uses static analysis to look up objects.

docs/get-started/docstring-examples.qmd

@@ -1,17 +1,86 @@
 ---
-title: 🚧 Examples
+title: Common issues and examples
 jupyter:
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
     name: python3
 ---
 
-```{python}
-from quartodoc import MdRenderer, preview
+This page provides examples for commonly encountered situations (and some funky ones).
+
+See the [numpydoc sections guide][numpydoc] for more information and examples.
+
+[numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html#sections
+
+## Examples: using code blocks
+
+Often, the Examples section of docstrings contain code examples.
+
+The Examples section supports two formats for code examples:
+
+* **doctest syntax** - code starts with `>>>`.
+* **markdown syntax** - surrounding code with three backticks (```` ``` ````)
+* **quarto syntax** - similar to markdown syntax (e.g. ```` ```{python} ````), but will execute code in the docs.
+
+Below is an example including each.
+
 
-renderer = MdRenderer()
 ```
+    Examples
+    --------
+    
+    doctest syntax:
+    
+    >>> 1 + 1
+    2
+    
+    markdown syntax:
+    
+    ```python
+    1 + 1
+    ```
+    
+    quarto syntax:
+    note that the "\" should be removed.
+    
+    ```\{python}
+    1 + 1
+    ```
+```
+
+
+## Examples, etc..: the "s" matters
+
+The numpydoc spec pluralizes section most names.
+If you leave off the "s", then they may be misparsed.
+
+For example, the docstring below erroneously has a "Return" section:
+
+```
+Return
+------
+
+some_name: int
+    a description of the return result
+```
+
+In this case, the section won't be parsed, but written directly into the doc page.
+This means that "Return" would show up as a level 2 header.
+
+Here is a list of pluralized section names:
+
+* Parameters
+* Returns
+* Yields
+* Receives
+* Other Parameters
+* Raises
+* Warns
+* Warnings
+* Notes
+* References
+* Examples
 
 ## Returns: using type annotation
 
@@ -36,6 +105,4 @@ def f() -> int:
         A number
     """
 
-```
-
-TODO: need to load as a griffe object somehow.
+```