Configuring content

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> followed by any additional options.

For example, below is a single content element, MdRenderer, without additional options.

contents:
  - MdRenderer

Instead of documenting the entire MdRenderer class, we can only document the MdRenderer.render method by setting name: MdRenderer followed by the members option:

contents:
  - name: MdRenderer
    members:
      - render

In the following sections, we’ll discuss different options for configuring content.

Looking up objects

Finding Python objects to document involves two pieces of configuration:

the package name.
a list of objects for content.

quartodoc can look up a wide variety of objects, including functions, modules, classes, attributes, and methods:

quartodoc:
  package: quartodoc
  sections:
    - title: Some section
      desc: ""
      contents:
        - get_object        # function: quartodoc.get_object
        - ast.preview       # submodule func: quartodoc.ast.preview
        - MdRenderer        # class: quartodoc.MdRenderer
        - MdRenderer.render # method: quartodoc.MDRenderer.render
        - renderers         # module: quartodoc.renderers

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 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 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:

Name	Type	Description
embedded		Embed documentation inside the parent object’s documentation.
flat		Include documentation after the parent object’s documentation.
separate		Put documentation for members on their own, separate pages.
linked		Include only a table of links to members (which may not be documented).

You can specify a style for displaying members by setting the children option in the config:

quartodoc:
  package: quartodoc
  sections:
    - title: Some section
      desc: ""
      contents:

        # set the children option, so that methods get documented
        # on separate pages. MdRenderer's docs will include a summary
        # table that links to each page.
        - name: MdRenderer
          children: separate

Setting default options

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.

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 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.

Manual

quartodoc:
  package: quartodoc
  sections:
    - title: "Some section"

      # options set manually ---
      contents:
        - name: MdRenderer
          members: []
        - name: Builder
          members: []

With options

quartodoc:
  package: quartodoc
  sections:
    - title: "Some section"

      # default options ---
      options:
        members: []
      
      contents:
        - MdRenderer
        - Builder

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:

- title: Some section
  options: &no-members
    members: []
  content:
    - ThingA
    - ThingB
- title: Another section
  options: *no-members
  content:
    - ThingC

The code above uses &no-members to name the options in the first section “no-members”, then *no-members to reference it in the second section. The & and * are called an anchor and alias, respectively, in YAML.

Where to put options

You can specify options in either the top-level config, or individual Sections.

quartodoc:
  package: quartodoc

  # set options on the top-level config.
  # this will apply to all pieces of content.
  options:
    include_attributes: false
  sections:
    - contents:
        - MdRenderer

      # set options in an individual section.
      # in thise case, it resets include_attributes back
      # to defaulting as true
      options:
        include_attributes: true

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.

# (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.

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.

contents:
  - name: get_object
    dynamic: true

Reference page sub-sections

quartodoc supports two levels of grouping on the reference page. Use the subtitle: option to add an additional level of grouping.

For example, the code below creates an API reference page with one top-level section (“Some section”), with two sub-sections inside it.

quartodoc:
  package: quartodoc
  sections:
    - title: Some section

    - subtitle: Stuff A
      desc: This is subsection A
      contents:
        - MdRenderer

    - subtitle: Stuff B
      desc: This is subsection B
      contents:
        - get_object

Grouping on a page

By default, content in each section gets included in the same index table, with each piece of content documented on its own page.

For example, consider the config below.

quartodoc:
  package: quartodoc
  sections:
    - title: Cool functions
      desc: ""
      contents:
        - get_object
        - name: MdRenderer
          members: ["render"]

Both get_object and MdRenderer will be:

summarized and linked to in the “Cool functions” section of the index.
documented on their own, separate pages.

Page layout element

Use a custom page element to group object documentation on the same page.

Custom page elements are specified by including a kind: <element name> field.

Separate

quartodoc:
  package: quartodoc
  sections:
    - title: Cool functions
      desc: ""

      # normal contents setup ----
      contents:
        - get_object
        - name: MdRenderer
          members: ["render"]

Grouped on same page

quartodoc:
  package: quartodoc
  sections:
    - title: Cool functions
      desc: ""

      # contents with a page grouping ----
      contents:
        - kind: page
          path: some_funcs
          contents:
            - get_object
            - name: MdRenderer
              members: ["render"]

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.

Documenting source files that are not a package

In some cases you might want to create a page for a bunch of Python modules that are not a package.

Say you have a repository that look like this:

project
├── config
├── data
├── docs
├── notebooks
├── src

Where src is the place where you have your .py files and docs is where your _quarto.yml is.

To make a quartodoc page of this project you have to set the package to null and tell Quarto where quartodoc should look. Then you can reference each file as usual with file.function.

Example:

quartodoc:
  package: null
  source_dir: ../src

  # write sidebar data to this file
  sidebar: _sidebar.yml

  sections:
    - title: Some functions
      desc: Some description
      contents:
        # the functions being documented in the package.
        # you can refer to anything: class methods, modules, etc..
        - analysis.plot_my_vars
        - training.train_and_evaluate

All content options

Below is a summary of all the options that can be applied to individual content entries.

Name	Type	Description
name	str	Name of the object. This should be the path needed to import it.
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).
members		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 “_”
include_imports		Whether to include members that were imported from somewhere else.
include_empty		Whether to include members with no docstring.
include_inherited		Whether to include members inherited from a parent class.
include_attributes		Whether to include attributes.
include_classes		Whether to include classes.
include_functions		Whether to include functions.
include		(Not implemented). A list of members to include.
exclude		A list of members to exclude. This is performed last, in order to subtract from the results of options like include_functions.
dynamic		Whether to dynamically load docstring. By default docstrings are loaded using static analysis. dynamic may be a string pointing to another object, 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.
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.