Merge pull request #148 from machow/docs-misc-fixes

docs: miscellaneous updates

Author: machow

docs/get-started/basic-content.qmd

@@ -29,7 +29,8 @@ contents:
       - render
 ```
 
-Behind the scenes, quartodoc represents each content entry as a [](`quartodoc.Auto`) element, since it specifies how to automatically document some object.
+In the following sections, we'll discuss different options for configuring content.
+
 
 ## Looking up objects
 
@@ -164,6 +165,7 @@ quartodoc:
       # contents with a page grouping ----
       contents:
         - kind: page
+          path: some_funcs
           contents:
             - get_object
             - name: MdRenderer
@@ -173,6 +175,15 @@ quartodoc:
 :::
 ::::::
 
+Note these three important pieces of the page entry:
+
+* `kind: page` - indicates that we are creating a page
+* `path:` - specifies what the name of the page will be in the generated docs.
+  For example, `path: some_funcs` in the config above produces a file called
+  `some_funcs.qmd` in the API reference folder.
+* `contents:` - lists out the contents of the page.
+
+
 
 ## Setting default package path
 
@@ -204,6 +215,10 @@ quartodoc:
           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.
@@ -232,4 +247,4 @@ In this case, you can set the dynamic option on a piece of content.
 contents:
   - name: get_object
     dynamic: true
-```
+```

docs/get-started/overview.qmd

@@ -46,9 +46,18 @@ First, create a `_quarto.yml` file with the following:
 project:
   type: website
 
+# tell quarto to read the generated sidebar
+metadata-files:
+  - _sidebar.yml
+
+
 quartodoc:
   # the name used to import the package
   package: quartodoc
+
+  # write sidebar data to this file
+  sidebar: _sidebar.yml
+
   sections:
     - title: Some functions
       desc: Functions to inspect docstrings.

quartodoc/ast.py

@@ -160,9 +160,17 @@ def tuple_to_data(el: "tuple[ds.DocstringSectionKind, str]"):
 
 @dispatch
 def fields(el: BaseModel):
+    # TODO: this is the only quartodoc specific code.
+    # pydantic seems to copy MISSING() when it's a default, so we can't
+    # whether a MISSING() is the default MISSING(). Instead, we'll just
+    # use isinstance for this particular class
+    from .layout import MISSING
+
     # return fields whose values were not set to the default
     field_defaults = {mf.name: mf.default for mf in el.__fields__.values()}
-    return [k for k, v in el if field_defaults[k] is not v]
+    return [
+        k for k, v in el if field_defaults[k] is not v if not isinstance(v, MISSING)
+    ]
 
 
 @dispatch

quartodoc/layout.py

@@ -203,6 +203,9 @@ class Auto(_Base):
         to return an alias for that object.
     children:
         Style for presenting members. Either separate, embedded, or flat.
+    package:
+        If specified, object lookup will be relative to this path.
+
 
     """
 
@@ -214,6 +217,7 @@ class Auto(_Base):
     exclude: Optional[str] = None
     dynamic: Union[bool, str] = False
     children: ChoicesChildren = ChoicesChildren.embedded
+    package: Union[str, None, MISSING] = MISSING()
 
 
 # TODO: rename to Default or something

quartodoc/renderers/md_renderer.py

@@ -426,7 +426,12 @@ def render(self, el: ds.DocstringSectionAttributes):
     @dispatch
     def render(self, el: ds.DocstringAttribute):
         annotation = self.render_annotation(el.annotation)
-        return el.name, self.render_annotation(annotation), el.description
+        row = [
+            sanitize(el.name),
+            self.render_annotation(annotation),
+            sanitize(el.description or "")
+        ]
+        return row
 
     # warnings ----
 

quartodoc/tests/test_builder_blueprint.py

@@ -70,3 +70,12 @@ def test_blueprint_visit_module(bp, dynamic):
     assert len(res.members) == 1
     assert res.members[0].name == "a_func"
     assert res.members[0].obj.path == path.replace(":", ".") + ".a_func"
+
+
+def test_blueprint_auto_package(bp):
+    auto = lo.Auto(name="a_func", package="quartodoc.tests.example")
+    res = bp.visit(auto)
+
+    assert isinstance(res, lo.DocFunction)
+    assert res.name == "a_func"
+    assert res.anchor == "quartodoc.tests.example.a_func"