Merge pull request #325 from machow/feat-description-lists

feat!: initial description-list support; render_header cleanup

docs/_quarto.yml

@@ -79,7 +79,9 @@ website:
 format:
   html:
     theme: cosmo
-    css: styles.css
+    css:
+      - api/_styles-quartodoc.css
+      - styles.css
     toc: true
 
 
@@ -88,7 +90,11 @@ quartodoc:
   dir: api
   package: quartodoc
   render_interlinks: true
+  renderer:
+    style: markdown
+    table_style: description-list
   sidebar: "api/_sidebar.yml"
+  css: "api/_styles-quartodoc.css"
   sections:
     - title: Preparation Functions
       desc: |

docs/get-started/overview.qmd

@@ -77,15 +77,20 @@ project:
 
 # tell quarto to read the generated sidebar
 metadata-files:
-  - _sidebar.yml
+  - api/_sidebar.yml
 
+# tell quarto to read the generated styles
+format:
+  css:
+    - api/_styles-quartodoc.css
 
 quartodoc:
   # the name used to import the package you want to create reference docs for
   package: quartodoc
 
-  # write sidebar data to this file
-  sidebar: _sidebar.yml
+  # write sidebar and style data
+  sidebar: api/_sidebar.yml
+  css: api/_styles-quartodoc.css
 
   sections:
     - title: Some functions

pyproject.toml

@@ -31,6 +31,7 @@ classifiers = [
 dynamic = ["version"]
 requires-python = ">=3.9"
 dependencies = [
+    "black",
     "click",
     "griffe >= 0.33",
     "sphobjinv >= 2.3.1",

quartodoc/autosummary.py

@@ -427,6 +427,8 @@ class Builder:
         The output path of the index file, used to list all API functions.
     sidebar:
         The output path for a sidebar yaml config (by default no config generated).
+    css:
+        The output path for the default css styles.
     rewrite_all_pages:
         Whether to rewrite all rendered doc pages, or only those with changes.
     source_dir:
@@ -486,6 +488,7 @@ def __init__(
         renderer: "dict | Renderer | str" = "markdown",
         out_index: str = None,
         sidebar: "str | None" = None,
+        css: "str | None" = None,
         rewrite_all_pages=False,
         source_dir: "str | None" = None,
         dynamic: bool | None = None,
@@ -502,6 +505,7 @@ def __init__(
         self.dir = dir
         self.title = title
         self.sidebar = sidebar
+        self.css = css
         self.parser = parser
 
         self.renderer = Renderer.from_config(renderer)
@@ -587,6 +591,12 @@ def build(self, filter: str = "*"):
             _log.info(f"Writing sidebar yaml to {self.sidebar}")
             self.write_sidebar(blueprint)
 
+        # css ----
+
+        if self.css:
+            _log.info(f"Writing css styles to {self.css}")
+            self.write_css()
+
     def write_index(self, blueprint: layout.Layout):
         """Write API index page."""
 
@@ -685,6 +695,22 @@ def write_sidebar(self, blueprint: layout.Layout):
         d_sidebar = self._generate_sidebar(blueprint)
         yaml.dump(d_sidebar, open(self.sidebar, "w"))
 
+    def write_css(self):
+        """Write default css styles to a file."""
+        from importlib_resources import files
+        from importlib_metadata import version
+
+        v = version("quartodoc")
+
+        note = (
+            f"/*\nThis file generated automatically by quartodoc version {v}.\n"
+            "Modifications may be overwritten by quartodoc build. If you want to\n"
+            "customize styles, create a new .css file to avoid losing changes.\n"
+            "*/\n\n\n"
+        )
+        with open(files("quartodoc.static") / "styles.css") as f:
+            Path(self.css).write_text(note + f.read())
+
     def _page_to_links(self, el: layout.Page) -> list[str]:
         # if el.flatten:
         #     links = []

quartodoc/renderers/base.py

@@ -17,6 +17,9 @@ def sanitize(val: str, allow_markdown=False):
     # sanitize common tokens that break tables
     res = val.replace("\n", " ").replace("|", "\\|")
 
+    # sanitize elements that get turned into smart quotes
+    res = res.replace("'", r"\'").replace('"', r"\"")
+
     # sanitize elements that can get interpreted as markdown links
     # or citations
     if not allow_markdown: