feat!: initial description-list support; render_header cleanup

[machow]

This PR implements description lists, based on the way py-shiny and plotnine extended the renderer in their docs.

While in the Renderer, I'll work on...

• migrating to use the quartodoc.pandoc submodule.
• consolidate more header generation into the .render_header() method.
• planning out nice HTML classes, so it's easier to style everything

Backwards incompatible changes:

• render(self, dc.Object | dc.Alias) now calls render(self, dc.Docstring), rather than iterating over the docstring itself.
  • This makes the printout of dc.Docstring renders in snapshot tests look a bit nicer.

HTML overview

Here's a rough sketch of the HTML structure rendered by quarto, using PUG:

// Doc example for quartodoc.MdRenderer
//
// Sections are automatically added around headers by quarto
// and we can add ids or classes to them
section.level1.quartodoc-MdRenderer.quartodoc(id='quartodoc.MdRenderer')

  // object title ----
  h1.quartodoc-MdRenderer.quartodoc MdRenderer

  // object signature ----
  p
    code
      | MdRenderer(self, header_level=1, show_signature=True ...)
  // doc section: short description ---
  p Render docstrings to markdown.

  // doc section: parameters ---
  section#parameters.level2.parameters
    h2.parameters.doc-section.doc-section-parameters.anchored(data-anchor-id='parameters')
      | Parameters
      a.anchorjs-link(...)

    // parameters definition list ---
    dl
      dt
        span.parameter-name
          code header_level
        span.parameter-annotation-sep :
        span.parameter-annotation
          a(href='https://docs.python.org/3/library/functions.html#int') int
        span.parameter-default-sep  =
        span.span-parameter-default
          code 1
      dd
        p The level of the header (e.g. 1 is the biggest).

  // doc section: example ---
  section#examples.level2.examples
    h2.examples.doc-section.doc-section-examples.anchored(data-anchor-id='examples')
      | Examples
      a.anchorjs-link(...)
    #cb1.sourceCode
      pre.sourceCode.python.code-with-copy.

TODO:

• Adding CSS styles to quartodoc sites (with description lists, you will need to add styles for them to look reasonable).
• Diagram

[machow]

rebased against main

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

Attention: Patch coverage is 90.47619% with 12 lines in your changes missing coverage. Please review.

Project coverage is 88.46%. Comparing base (81cccdf) to head (9005913).
Report is 2 commits behind head on main.

Files	Patch %	Lines
quartodoc/autosummary.py	27.27%	8 Missing ⚠️
quartodoc/renderers/md_renderer.py	95.78%	4 Missing ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #325      +/-   ##
==========================================
- Coverage   88.49%   88.46%   -0.03%     
==========================================
  Files          37       37              
  Lines        2843     2931      +88     
==========================================
+ Hits         2516     2593      +77     
- Misses        327      338      +11     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[machow]

This is mostly complete, but we need to figure out how users will include the necessary css (e.g. could educate or orchestrate).

[machow]

It seems like for css, we could provide an extension that includes the necessary css via quarto's lua add_html_dependencies().

If we do this, we should make obvious people how to escape hatch by copying the css file into their own project.