feat!: initial description-list support; render_header cleanup

machow commented 10 months ago

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.&nbsp;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 commented 2 months ago

rebased against main

codecov-commenter commented 2 months ago

:warning: Please install the 'codecov app svg image' 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 :warning:
quartodoc/renderers/md_renderer.py	95.78%	4 Missing :warning:

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

Additional details and impacted files

```diff @@ 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 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

machow commented 2 months ago

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

machow commented 2 months ago

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.

machow / quartodoc