Usage: quartodoc build [OPTIONS]
diff --git a/get-started/basic-content.html b/get-started/basic-content.html
index a2f9e39..2ed4682 100644
--- a/get-started/basic-content.html
+++ b/get-started/basic-content.html
@@ -2,7 +2,7 @@
-
+
@@ -104,6 +104,7 @@
}
+
@@ -409,12 +410,12 @@ Module and class
embedded
Embed documentation inside the parent object’s documentation.
+Embed documentation inside the parent object's documentation.
flat
Include documentation after the parent object’s documentation.
+Include documentation after the parent object's documentation.
separate
@@ -698,17 +699,17 @@ All content options
signature_name
Style of name to use in the signature. Can be “relative”, “full”, or “short”. Relative is whatever was used as the name argument, full is the fully qualified path the object, and short is the name of the object (i.e. no periods).
+Style of name to use in the signature. Can be "relative", "full", or "short". Relative is whatever was used as the name argument, full is the fully qualified path the object, and short is the name of the object (i.e. no periods).
members
A list of members, such as attributes or methods on a class, to document.
+A list of members, such as attributes or methods on a class, to document. If members is specified, no other includes or excludes are applied.
include_private
Whether to include members starting with “_”
+Whether to include members starting with "_"
include_imports
@@ -748,7 +749,7 @@ All content options
exclude
(Not implemented). A list of members to exclude.
+A list of members to exclude. This is performed last, in order to subtract from the results of options like include_functions.
dynamic
@@ -766,6 +767,11 @@ All content optionsIf specified, object lookup will be relative to this path.
+member_order
+Order to present members in, either "alphabetical" or "source" order. Defaults to alphabetical sorting.
+
+
member_options
Options to apply to members. These can include any of the options above.
diff --git a/get-started/basic-docs.html b/get-started/basic-docs.html
index dc0ea53..bed1f63 100644
--- a/get-started/basic-docs.html
+++ b/get-started/basic-docs.html
@@ -2,7 +2,7 @@
-
+
@@ -104,6 +104,7 @@
}
+
@@ -362,8 +363,8 @@ Top-level options
The quartodoc section takes a style field, specifying which quartodoc.Builder to use (currently “pkgdown” or “single-page”; see Examples).
-
@@ -377,87 +378,93 @@ Top-level options
-packagepackage
str
The name of the package.
required
-sections‘list[Any]’
+sections
+'list[Any]'
A list of sections, with items to document.
tuple()
-version‘str | None’
+version
+'str | None'
The package version. By default this attempts to look up the current package version (TODO).
None
-dirdir
str
Name of API directory.
'reference'
-titletitle
str
Title of the API index page.
'Function reference'
-renderer‘dict | Renderer | str’
+renderer
+'dict | Renderer | str'
The renderer used to convert docstrings (e.g. to markdown).
'markdown'
-options‘dict | None’
+options
+'dict | None'
Default options to set for all pieces of content (e.g. include_attributes).
None
-out_indexout_index
str
The output path of the index file, used to list all API functions.
None
-sidebar‘str | None’
+sidebar
+'str | None'
The output path for a sidebar yaml config (by default no config generated).
None
-rewrite_all_pagescss
+'str | None'
+The output path for the default css styles.
+None
+
+rewrite_all_pages
Whether to rewrite all rendered doc pages, or only those with changes.
False
-
-source_dir‘str | None’
-A directory where source files to be documented live. This is only necessary if you are not documenting a package, but collection of scripts. Use a “.” to refer to the current directory.
+
+source_dir
+'str | None'
+A directory where source files to be documented live. This is only necessary if you are not documenting a package, but collection of scripts. Use a "." to refer to the current directory.
None
-
-dynamic
+dynamic
bool | None
Whether to dynamically load all python objects. By default, objects are loaded using static analysis.
None
-
-render_interlinks
+render_interlinks
bool
Whether to render interlinks syntax inside documented objects. Note that the interlinks filter is required to generate the links in quarto.
False
-
-parser
+parser
Docstring parser to use. This correspond to different docstring styles, and can be one of “google”, “sphinx”, and “numpy”. Defaults to “numpy”.
+Docstring parser to use. This correspond to different docstring styles, and can be one of "google", "sphinx", and "numpy". Defaults to "numpy".
'numpy'
diff --git a/get-started/crossrefs.html b/get-started/crossrefs.html
index fa1277e..b682dc2 100644
--- a/get-started/crossrefs.html
+++ b/get-started/crossrefs.html
@@ -2,7 +2,7 @@
-
+
@@ -70,6 +70,7 @@
}
+
diff --git a/get-started/dev-big-picture.html b/get-started/dev-big-picture.html
index eaa0024..6d956f2 100644
--- a/get-started/dev-big-picture.html
+++ b/get-started/dev-big-picture.html
@@ -2,7 +2,7 @@
-
+
@@ -104,6 +104,7 @@
}
+
@@ -360,7 +361,7 @@ Overview
The Builder
The code below shows a Builder object being loaded from a _quarto.yml config (loaded as a Python dictionary).
-
+
import yaml
from quartodoc import Builder, blueprint, collect, MdRenderer
@@ -381,19 +382,19 @@ The Builder
builder = Builder.from_quarto_config(cfg)
builder
-<quartodoc.autosummary.BuilderPkgdown at 0x7fd28828de70>
+<quartodoc.autosummary.BuilderPkgdown at 0x7fafc2df2380>
Note that .from_quarto_config used the style: field to decide which Builder to create (in this case, BuilderPkgdown).
We can view the config as a layout.Layout, by looking at the .layout attribute.
-
+
builder.layout
-Layout(sections=[Section(kind='section', title='Some section', subtitle=None, desc='Some description', package=MISSING(), contents=[Auto(signature_name='relative', members=['render', 'summarize'], include_private=False, include_imports=False, include_empty=False, include_inherited=False, include_attributes=True, include_classes=True, include_functions=True, include=None, exclude=None, dynamic=None, children=<ChoicesChildren.separate: 'separate'>, package=MISSING(), member_options=None, kind='auto', name='MdRenderer')], options=None)], package='quartodoc', options=None)
+Layout(sections=[Section(kind='section', title='Some section', subtitle=None, desc='Some description', package=MISSING(), contents=[Auto(signature_name='relative', members=['render', 'summarize'], include_private=False, include_imports=False, include_empty=False, include_inherited=False, include_attributes=True, include_classes=True, include_functions=True, include=None, exclude=None, dynamic=None, children=<ChoicesChildren.separate: 'separate'>, package=MISSING(), member_order='alphabetical', member_options=None, kind='auto', name='MdRenderer')], options=None)], package='quartodoc', options=None)
This can be a bit difficult to read, so quartodoc implements a preview function, which spaces things out.
-
+
from quartodoc import preview
preview(builder.layout)
@@ -418,7 +419,7 @@ The Builder
The content entry MdRenderer is represented by an 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 this first piece of content containing MdRenderer:
-
+
content = builder.layout.sections[0].contents[0]
preview(content)
@@ -435,7 +436,7 @@ The Builder
From config to blueprint
The code below shows how blueprint() transforms the Auto entry for MdRenderer.
-
+
bp = blueprint(builder.layout)
bp_contents = bp.sections[0].contents[0]
preview(bp_contents, max_depth=3)
@@ -457,7 +458,7 @@ From config to bl
The content of the page is a layout.DocClass. This element holds everything needed to render this doc, including the class signature and parsed docstring.
Importantly, the .members attribute stores how to render the class methods we listed in our configuration yaml, .render() and .summarize():
-
+
preview(bp_contents.contents[0].members, max_depth=2)
█─list
@@ -478,7 +479,7 @@ Collecting page
pages - each page to be rendered.
items - information on where each documented object lives in the site, which is used for things like interlinks.
-
+
pages, items = collect(bp, builder.dir)
preview(pages, max_depth=3)
@@ -498,7 +499,7 @@ Collecting page
The code below shows a preview of the items.
-
+
preview(items, max_depth=2)
█─list
@@ -536,19 +537,21 @@ Collecting page
Rendering and writing
A Builder instantiates a Renderer (like MdRenderer). Use the .renderer attribute to access it:
-
+
builder.renderer
-<quartodoc.renderers.md_renderer.MdRenderer at 0x7fd2882a8d90>
+<quartodoc.renderers.md_renderer.MdRenderer at 0x7fafc1b10be0>
The render method of of the MdRenderer returns a markdown string that can be rendered by Quarto:
-
+
print(builder.renderer.render(pages[0]))
# render { #quartodoc.MdRenderer.render }
-`MdRenderer.render(el)`
+```python
+MdRenderer.render(el)
+```
diff --git a/get-started/dev-dataclasses.html b/get-started/dev-dataclasses.html
index 755f6e0..a90328f 100644
--- a/get-started/dev-dataclasses.html
+++ b/get-started/dev-dataclasses.html
@@ -2,7 +2,7 @@
-
+
@@ -68,6 +68,7 @@
}
+
diff --git a/get-started/dev-docstrings.html b/get-started/dev-docstrings.html
index fcf27d3..be1eaf9 100644
--- a/get-started/dev-docstrings.html
+++ b/get-started/dev-docstrings.html
@@ -2,7 +2,7 @@
-
+
@@ -104,6 +104,7 @@
}
+
@@ -366,7 +367,7 @@ Docstring structure
Reading docstrings
Use the function get_object to read in a docstring from a module.
-
+
from quartodoc import get_object, preview
f_obj = get_object("quartodoc", "get_object")
@@ -384,7 +385,7 @@ Reading docstrings
Function name
-
+
f_obj.name
'get_object'
@@ -393,16 +394,16 @@ Function name
Function parameters
-
+
f_obj.parameters
-Parameters(Parameter(name='path', annotation=ExprName(name='str', parent=Module(PosixPath('/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/quartodoc/autosummary.py'))), kind=<ParameterKind.positional_or_keyword: 'positional or keyword'>, default=None), Parameter(name='object_name', annotation="'str | None'", kind=<ParameterKind.positional_or_keyword: 'positional or keyword'>, default='None'), Parameter(name='parser', annotation=ExprName(name='str', parent=Module(PosixPath('/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/quartodoc/autosummary.py'))), kind=<ParameterKind.positional_or_keyword: 'positional or keyword'>, default="'numpy'"), Parameter(name='load_aliases', annotation=None, kind=<ParameterKind.positional_or_keyword: 'positional or keyword'>, default='True'), Parameter(name='dynamic', annotation=None, kind=<ParameterKind.positional_or_keyword: 'positional or keyword'>, default='False'), Parameter(name='loader', annotation=ExprBinOp(left='None', operator='|', right=ExprName(name='GriffeLoader', parent=Module(PosixPath('/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/quartodoc/autosummary.py')))), kind=<ParameterKind.positional_or_keyword: 'positional or keyword'>, default='None'))
+Parameters(Parameter(name='path', annotation=ExprName(name='str', parent=Module(PosixPath('/opt/hostedtoolcache/Python/3.10.15/x64/lib/python3.10/site-packages/quartodoc/autosummary.py'))), kind=<ParameterKind.positional_or_keyword: 'positional or keyword'>, default=None), Parameter(name='object_name', annotation="'str | None'", kind=<ParameterKind.positional_or_keyword: 'positional or keyword'>, default='None'), Parameter(name='parser', annotation=ExprName(name='str', parent=Module(PosixPath('/opt/hostedtoolcache/Python/3.10.15/x64/lib/python3.10/site-packages/quartodoc/autosummary.py'))), kind=<ParameterKind.positional_or_keyword: 'positional or keyword'>, default="'numpy'"), Parameter(name='load_aliases', annotation=None, kind=<ParameterKind.positional_or_keyword: 'positional or keyword'>, default='True'), Parameter(name='dynamic', annotation=None, kind=<ParameterKind.positional_or_keyword: 'positional or keyword'>, default='False'), Parameter(name='loader', annotation=ExprBinOp(left='None', operator='|', right=ExprName(name='GriffeLoader', parent=Module(PosixPath('/opt/hostedtoolcache/Python/3.10.15/x64/lib/python3.10/site-packages/quartodoc/autosummary.py')))), kind=<ParameterKind.positional_or_keyword: 'positional or keyword'>, default='None'))
Raw docstring value
-
+
print(f_obj.docstring.value)
Fetch a griffe object.
@@ -441,14 +442,14 @@ Raw docstring value
Parsed docstring
-
+
f_obj.docstring.parsed
-[<_griffe.docstrings.models.DocstringSectionText at 0x7ff1b05d8fd0>,
- <_griffe.docstrings.models.DocstringSectionParameters at 0x7ff1a04acb50>,
- <_griffe.docstrings.models.DocstringSectionAdmonition at 0x7ff1a04aceb0>,
- <_griffe.docstrings.models.DocstringSectionExamples at 0x7ff1a04ac9a0>,
- <_griffe.docstrings.models.DocstringSectionReturns at 0x7ff1a04aef20>]
+[<_griffe.docstrings.models.DocstringSectionText at 0x7fc2b00d6fb0>,
+ <_griffe.docstrings.models.DocstringSectionParameters at 0x7fc29c9cdf60>,
+ <_griffe.docstrings.models.DocstringSectionAdmonition at 0x7fc29c9cdbd0>,
+ <_griffe.docstrings.models.DocstringSectionExamples at 0x7fc29c9cdc30>,
+ <_griffe.docstrings.models.DocstringSectionReturns at 0x7fc29c8cc160>]
The docstring into a tree lets us define visitors, which can visit each element and do useful things. For example, print a high-level overview of its structure, or render it to markdown.
@@ -457,14 +458,14 @@ Parsed docstring
Previewing docstrings
Use the preview function to see the overall structure of a parsed docstring.
-
+
from quartodoc import get_object, preview
f_obj = get_object("quartodoc", "get_object")
Raw docstring
-
+
print(f_obj.docstring.value)
Fetch a griffe object.
@@ -503,7 +504,7 @@ Raw docstring
Preview
-
+
preview(f_obj.docstring.parsed)
█─list
diff --git a/get-started/dev-prepare.html b/get-started/dev-prepare.html
index 4c774b9..7a88f33 100644
--- a/get-started/dev-prepare.html
+++ b/get-started/dev-prepare.html
@@ -2,7 +2,7 @@
-
+
@@ -104,6 +104,7 @@
}
+
@@ -346,7 +347,7 @@ Components: Auto, blueprint, collect
-
+
from quartodoc import collect, preview
from quartodoc import MdRenderer
import yaml
@@ -356,7 +357,7 @@ Auto: Con
The Auto class contains data about how you wish to render a specific Python object, which you typically set in configuration options via the quartodoc section of your _quarto.yml file. In other words, Auto is a data structure that represents the configuration options for a specific Python object.
In the previous section, be demonstrated how we can find the Auto object corresponding to the MdRenderer class from our yaml configuration:
We can find the Auto object corresponding to the python object from our yaml configuration like this:
-
+
import yaml
from quartodoc import Builder
@@ -377,29 +378,29 @@ Auto: Con
auto_from_yml = builder.layout.sections[0].contents[0]
print(auto_from_yml)
-signature_name='relative' members=['render', 'summarize'] include_private=False include_imports=False include_empty=False include_inherited=False include_attributes=True include_classes=True include_functions=True include=None exclude=None dynamic=None children=<ChoicesChildren.separate: 'separate'> package=MISSING() member_options=None kind='auto' name='MdRenderer'
+signature_name='relative' members=['render', 'summarize'] include_private=False include_imports=False include_empty=False include_inherited=False include_attributes=True include_classes=True include_functions=True include=None exclude=None dynamic=None children=<ChoicesChildren.separate: 'separate'> package=MISSING() member_order='alphabetical' member_options=None kind='auto' name='MdRenderer'
We can see many of the configuration options such as members, name and children as well as other options we didn’t specify but are set to their default values. For example, we didn’t set the option for dynamic but it is set to false by default.
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:
-
+
from quartodoc import Auto
auto = Auto(name = "quartodoc.MdRenderer",
signature_name = 'short')
print(auto)
-signature_name='short' members=None include_private=False include_imports=False include_empty=False include_inherited=False include_attributes=True include_classes=True include_functions=True include=None exclude=None dynamic=None children=<ChoicesChildren.embedded: 'embedded'> package=MISSING() member_options=None kind='auto' name='quartodoc.MdRenderer'
+signature_name='short' members=None include_private=False include_imports=False include_empty=False include_inherited=False include_attributes=True include_classes=True include_functions=True include=None exclude=None dynamic=None children=<ChoicesChildren.embedded: 'embedded'> package=MISSING() member_order='alphabetical' member_options=None kind='auto' name='quartodoc.MdRenderer'
However, since we didn’t specify any options, this is not the same Auto that we got from the yaml. For example, the members option is not set to ["render", "summarize"] as it was in the yaml. Instead, it is set to None which means that all members will be included. We can see this by looking at the obj attribute of the Auto object:
-
+
print(auto.members)
None
To set this option, we can pass it to the Auto constructor:
-
+
auto = Auto(name = "quartodoc.MdRenderer",
members = ["render", "summarize"]
)
@@ -407,7 +408,7 @@ Auto: Con
assert auto.members == auto_from_yml.members
print(auto)
-signature_name='relative' members=['render', 'summarize'] include_private=False include_imports=False include_empty=False include_inherited=False include_attributes=True include_classes=True include_functions=True include=None exclude=None dynamic=None children=<ChoicesChildren.embedded: 'embedded'> package=MISSING() member_options=None kind='auto' name='quartodoc.MdRenderer'
+signature_name='relative' members=['render', 'summarize'] include_private=False include_imports=False include_empty=False include_inherited=False include_attributes=True include_classes=True include_functions=True include=None exclude=None dynamic=None children=<ChoicesChildren.embedded: 'embedded'> package=MISSING() member_order='alphabetical' member_options=None kind='auto' name='quartodoc.MdRenderer'
Understanding the Auto object is helpful for debugging quartodoc. If you find that a configuration option is not being set as you expect, you can create an Auto object for the Python object in question and compare it to the Auto object that you expect to be created from your yaml configuration.
@@ -415,7 +416,7 @@ Auto: Con
blueprint: Parse Metadata From Objects
blueprint parses all of the metadata about the python object and stores it in a hierarchal tree structure that is convenient for a renderer to transform into a renderable format like HTML or Markdown. For example, here is the blueprint for the MdRenderer class:
-
+
from quartodoc import blueprint
doc = blueprint(auto)
preview(doc, max_depth=2)
@@ -438,7 +439,7 @@
To give you a sense of this tree structure, we can look at the obj.docstring field of the above blueprint, which contains information about the Python docstring:
-
+
preview(doc.obj.docstring, max_depth=2)
█─Docstring
@@ -451,7 +452,7 @@
We can see from this output that the parser for the docstring is numpy, which means the docstring is expected to be in the numpy style.
Furthermore, we can see from the tree structure that the DocstringSectionText is stored as the first element in a list under the parsed attribute:
-
+
preview(doc.obj.docstring.parsed[0])
█─DocstringSectionText
@@ -461,7 +462,7 @@
DocstringSectionText stores the “text” field of a numpy style docstring, which is the first line of the docstring, which is otherwise known as the short summary. Furthermore, we can see from the output above that the actual text of this short summary is stored in the value attribute:
-
+
docstr_firstln_value = doc.obj.docstring.parsed[0].value
print(docstr_firstln_value)
@@ -469,7 +470,7 @@
We can check the docstring of MdRenderer to see that this is indeed the first line of the docstring:
-
+
from inspect import getdoc
docstr_firstln = getdoc(MdRenderer).splitlines()[0]
@@ -484,7 +485,7 @@
Layout & Sections
The 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:
-
+
import yaml
from quartodoc import Builder
@@ -523,7 +524,7 @@ Layout & Sections
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 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.
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:
-
+
from quartodoc import Auto, layout
auto = Auto(name = "quartodoc.MdRenderer",
@@ -538,7 +539,7 @@ Layout & Sections
)
We can view the layout by calling the preview function:
-
+
preview(lay,
max_depth=8,
compact=True)
@@ -559,7 +560,7 @@ Layout & Sections
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:
-
+
bp_layout = blueprint(lay)
preview(bp_layout,
max_depth=8,
@@ -599,9 +600,7 @@ Layout & Sections
├─signature_name = 'short'
├─members =
│ █─list
- │ ├─0 =
- │ │ █─DocFunction ...
- │ └─1 =
+ │ └─0 =
│ █─DocFunction ...
└─flat = False
@@ -610,7 +609,7 @@ Layout & Sections
Grouping docs on a 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.
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:
-
+