docs: document options block

Author: machow

docs/get-started/basic-content.qmd

@@ -99,6 +99,127 @@ quartodoc:
           children: separate
 ```
 
+
+## Setting default options
+
+The section above showed how you can set options like `members:` and `children:` on content.
+When specifying API documentation, you may need to specify the same options across multiple pieces of content.
+
+Use the `options:` field in a section to specify options to apply across all content in that section.
+
+For example, the config blocks below show how to document multiple classes without their members.
+
+:::::: {.columns}
+::: {.column}
+
+**Manual**
+
+```yaml
+quartodoc:
+  package: quartodoc
+  sections:
+    - title: "Some section"
+
+      # options set manually ---
+      contents:
+        - name: MdRenderer
+          members: []
+        - name: Builder
+          members: []
+```
+
+:::
+::: {.column}
+
+**With options**
+
+```yaml
+quartodoc:
+  package: quartodoc
+  sections:
+    - title: "Some section"
+
+      # default options ---
+      options:
+        members: []
+      
+      contents:
+        - MdRenderer
+        - Builder
+```
+
+:::
+::::::
+
+Note that the **with options** block sets `members: []` inside `options`.
+This sets `members: []` as the default for each piece of content.
+
+## Specifying 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
+        
+        # (4) package set on individual content entry
+        - package: pandas
+          name: Series
+```
+
+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.
+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
+```
+
+
 ## Reference page sub-sections
 
 quartodoc supports two levels of grouping on the reference page.
@@ -210,67 +331,3 @@ Note these three important pieces of the page entry:
 * `contents:` - lists out the contents of the page.
 
 
-
-## 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
-        
-        # (4) package set on individual content entry
-        - package: pandas
-          name: Series
-```
-
-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.
-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
-```