Merge pull request #264 from machow/docs-review

Docs review

Author: machow

docs/_quarto.yml

@@ -83,9 +83,9 @@ quartodoc:
   render_interlinks: true
   sidebar: "api/_sidebar.yml"
   sections:
-    - title: Preperation Functions
+    - title: Preparation Functions
       desc: |
-        These functions fetch and analyze python objects, including parsing docstrings.
+        These functions fetch and analyze Python objects, including parsing docstrings.
         They prepare a basic representation of your doc site that can be rendered and built.
       contents:
         - Auto
@@ -123,10 +123,9 @@ quartodoc:
         - Builder.write_sidebar
         - Builder.create_inventory
 
-
     - title: Inventory links
       desc: |
-        Inventory files map a functions name to its corresponding url in your docs.
+        Inventory files map a function's name to its corresponding url in your docs.
         These functions allow you to create and transform inventory files.
       contents:
         - create_inventory

docs/get-started/basic-content.qmd

@@ -7,20 +7,20 @@ jupyter:
     name: python3
 ---
 
-Individual content entries (e.g. a function to be documented) can also be customized.
+Individual content entries (e.g. a function to be documented) can 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.
+Specify content options by setting `name: <content name>` followed by any additional options.
 
-For example, below is a piece of content, MdRenderer, specified without options.
+For example, below is a single content element, `MdRenderer`, without additional options.
 
 ```yaml
 contents:
   - MdRenderer
 ```
 
-We set it to only document its render method, by setting `name: MdRenderer` followed by the `members` option.
+Instead of documenting the entire `MdRenderer` class, we can only document the `MdRenderer.render` method by setting `name: MdRenderer` followed by the `members` option:
 
 ```yaml
 contents:
@@ -36,10 +36,10 @@ In the following sections, we'll discuss different options for configuring conte
 
 Finding Python objects to document involves two pieces of configuration:
 
-* the package name.
-* a list of objects for content.
+1.  the package name.
+2.  a list of objects for content.
 
-Note that quartodoc can look up anything---whether functions, modules, classes, attributes, or methods.
+quartodoc can look up a wide variety of objects, including functions, modules, classes, attributes, and methods:
 
 ```yaml
 quartodoc:
@@ -55,13 +55,13 @@ quartodoc:
         - renderers         # module: quartodoc.renderers
 ```
 
-The functions listed in `contents` are assumed to be imported from the package.
+The functions listed in `contents` are those that are available for import from the package (`quartodoc` in this instance).
 
 ## 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).
+Documentation for classes and modules can automatically include their members (e.g. class methods and attributes or everything defined inside a module, respectively).
 
-By default, all attributes and functions (including methods on a class) are documented by embedding them inside the module or class documentation.
+By default, all attributes and functions (including methods on a class) are presented in the `embedded` style, which means their documentation is located inside their respective module's or class's documentation.
 
 There are four styles for presenting child members:
 
@@ -82,7 +82,7 @@ res = extract_type(DocstringSectionAttributes, choices.docstring.parsed)[0]
 print(renderer.render(res))
 ```
 
-You can specify a style by setting the `children` option in the config:
+You can specify a style for displaying members by setting the `children` option in the config:
 
 ```yaml
 quartodoc:
@@ -102,12 +102,11 @@ quartodoc:
 
 ## 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.
+The section above showed how you can set options like `members:` (which is a list of the items you want to show) and `children:` (the style for presenting `members`) on content.
 
-Use the `options:` field in a section to specify options to apply across all content in that section.
+However, you may desire to set the same options across multiple pieces of content. In this case, you can set default options for a section that applies to all content in that section. You can use the `options:` field to accomplish this.
 
-For example, the config blocks below show how to document multiple classes without their members.
+For example, the config below shows how to document multiple classes _without_ any child members.  On the left, you can see the config without setting the default option, and on the right, you can see the config with the default option set.
 
 :::::: {.columns}
 ::: {.column}
@@ -151,12 +150,11 @@ quartodoc:
 :::
 ::::::
 
-Note that the **with options** block sets `members: []` inside `options`.
-This sets `members: []` as the default for each piece of content.
+By setting `members: []` in the options block, we are telling quartodoc to not include any members for each piece of content.
 
 ### Reusing options
 
-Options can be given a name, and re-used in multiple sections:
+Options can be given a name and re-used in multiple sections:
 
 ```yaml
 - title: Some section

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

@@ -28,7 +28,7 @@ The code below shows a Builder object being loaded from a `_quarto.yml` config (
 ```{python}
 import yaml
 
-from quartodoc import Builder, preview, blueprint, collect, MdRenderer
+from quartodoc import Builder, blueprint, collect, MdRenderer
 
 cfg = yaml.safe_load("""
 quartodoc:
@@ -48,7 +48,7 @@ builder
 ```
 
 Note that .from_quarto_config used the `style:` field to decide which Builder to create
-(in this case, PkgdownBuilder).
+(in this case, `BuilderPkgdown`).
 
 We can view the config as a [layout.Layout](`quartodoc.layout.Layout`), by looking at the `.layout` attribute.
 
@@ -59,6 +59,7 @@ builder.layout
 This can be a bit difficult to read, so quartodoc implements a [preview](`quartodoc.preview`) function, which spaces things out.
 
 ```{python}
+from quartodoc import preview
 preview(builder.layout)
 ```
 
@@ -69,14 +70,14 @@ a pipe connecting it to each of its arguments.
 * The content entry `MdRenderer` is represented by an [Auto](`quartodoc.Auto`) class.
   This specifies a Python object to look up and document.
 
-We can follow the path in the preview above, to pull out just the contents piece:
+We can follow the path in the preview above, to pull out just this first piece of content containing `MdRenderer`:
 
 ```{python}
 content = builder.layout.sections[0].contents[0]
 preview(content)
 ```
 
-Next, we'll look at `blueprint()`, which processes the layout, including transforming `Auto` objects into more concrete instructions.
+Next, we'll look at `blueprint()`, which processes the layout, including transforming `Auto` objects (like the one representing the `MdRenderer` above) into more concrete instructions.
 
 ## From config to blueprint
 
@@ -96,7 +97,7 @@ Notice two key pieces:
   This element holds everything needed to render this doc, including the class signature
   and parsed docstring.
 
-Importantly, the `.members` attribute specifies how to render the class methods we specified (`.render()` and `.summarize()`).
+Importantly, the `.members` attribute stores how to render the class methods we listed in our configuration yaml, `.render()` and `.summarize()`:
 
 ```{python}
 preview(bp_contents.contents[0].members, max_depth=2)
@@ -112,7 +113,7 @@ Before to building the site, we need to `collect()` all the pages.
 The [collect](`quartodoc.collect`) function pulls out two important pieces of information:
 
 * **pages** - each page to be rendered.
-* **items** - information on where each documented object lives in the site.
+* **items** - information on where each documented object lives in the site, which is used for things like [interlinks](interlinks.qmd).
 
 ```{python}
 pages, items = collect(bp, builder.dir)
@@ -130,21 +131,28 @@ Notice that if you wanted to look up `quartodoc.MdRenderer.render`, the first it
 
 ## Rendering and writing
 
-A `Builder` instantiates a `Renderer` (like [MdRenderer](`quartodoc.MdRenderer`)).
-Use the `.renderer` attribute to access it.
+A `Builder` instantiates a `Renderer` (like [](`~quartodoc.MdRenderer`)).
+Use the `.renderer` attribute to access it:
 
 ```{python}
 builder.renderer
 ```
 
+The `render` method of of the [](`~quartodoc.MdRenderer`) returns a markdown string that can be rendered by Quarto:
 ```{python}
 print(builder.renderer.render(pages[0]))
-
 ```
 
+:::{.callout-note}
+### Cross References
+
+The `{ #quartodoc.MdRenderer.render }` in the output above is extended Quarto markdown that is a [cross reference](https://quarto.org/docs/authoring/cross-references.html).
+
+:::
+
 ## Writing pages
 
-The builder has a number of methods it uses during build.
+The builder has a number of methods it uses while materializing files that will be rendered by Quarto.
 The main method is [.build()](`quartodoc.Builder.build`).
 See the [Builder section of the API](#api-builders) for a list of methods,
 or this [giant build process diagram](/get-started/extra-build-sequence.qmd) for a full breakdown.