Merge pull request #121 from machow/docs-overhaul

docs: site overhaul

Author: machow

.github/workflows/ci.yml

@@ -83,6 +83,8 @@ jobs:
           python -m pip install shiny shinylive
           python -m pip install --no-deps dascore==0.0.8
       - uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          version: "1.2.475"
       - name: Build docs
         run: |
           make docs-build

Makefile

@@ -13,7 +13,7 @@ docs/examples/%: examples/%/_site
 	rm -rf docs/examples/$*
 	cp -rv $< $@
 
-docs-build-examples: docs/examples/single-page docs/examples/pkgdown docs/examples/shiny
+docs-build-examples: docs/examples/single-page docs/examples/pkgdown
 
 docs-build: docs-build-examples
 	cd docs && quarto add --no-prompt ..

docs/_quarto.yml

@@ -4,7 +4,6 @@ project:
   resources:
     - examples/single-page
     - examples/pkgdown
-    - examples/shiny
 
 metadata-files:
   - api/_sidebar.yml
@@ -19,16 +18,75 @@ interlinks:
     griffe:
       url: https://mkdocstrings.github.io/griffe/
 
+website:
+  title: "quartodoc"
+  page-navigation: true
+  navbar:
+    left:
+      - file: get-started/overview.qmd
+        text: Get Started
+      - file: examples/
+        text: Examples
+      - href: api/
+        text: Reference
+    right:
+      - icon: github
+        href: https://github.com/machow/quartodoc/
+  sidebar:
+    - id: get-started
+      title: Get Started
+      style: floating
+      align: left
+      contents:
+        - get-started/overview.qmd
+        - section: "Basic Use"
+          contents:
+            - get-started/basic-docs.qmd
+            - get-started/basic-content.qmd
+            - get-started/basic-building.qmd
+            - get-started/crossrefs.qmd
+            - get-started/interlinks.qmd
+            - get-started/sidebar.qmd
+            - get-started/extending.qmd
+
+        - section: "Docstrings"
+          contents:
+            - get-started/docstring-style.qmd
+            - get-started/docstring-examples.qmd
+
+        - section: "Programming"
+          contents:
+            - get-started/dev-big-picture.qmd
+            - get-started/dev-prepare.qmd
+            - get-started/docstrings.qmd
+            - get-started/renderers.qmd
+            - get-started/dev-dataclasses.qmd
+        - section: "Extra Topics"
+          contents:
+            - get-started/extra-build-sequence.qmd
+
+
+format:
+  html:
+    theme: cosmo
+    css: styles.css
+    toc: true
+
+
 quartodoc:
   style: pkgdown
   dir: api
   package: quartodoc
   sidebar: "api/_sidebar.yml"
   sections:
-    - title: Inspection
+    - title: Preperation Functions
       desc: |
-        These functions Fetch and analyze python objects, including parsing docstrings.
+        These functions fetch and analyze python objects, including parsing docstrings.
+        They prepare a basic representation of your doc site that can be rendered and built.
       contents:
+        - Auto
+        - blueprint
+        - collect
         - get_object
         - preview
 
@@ -57,12 +115,12 @@ quartodoc:
         - kind: auto
           name: Builder
           members: []
+        - Builder.from_quarto_config
         - Builder.build
-        - Builder.do_blueprint
-        - Builder.do_collect
-        - Builder.do_summarize
         - Builder.write_index
         - Builder.write_doc_pages
+        - Builder.write_sidebar
+        - Builder.create_inventory
 
 
     - title: Inventory links
@@ -73,18 +131,28 @@ quartodoc:
         - create_inventory
         - convert_inventory
 
-    - title: Data models
+    - title: "Data models: structural"
       desc: |
-        Classes for specifying the exact layout of your docs.
+        Classes for specifying the broad structure your docs.
       contents:
         - kind: "page"
-          path: "layouts"
+          path: "layouts-structure"
           flatten: true
           contents:
             - layout.Layout
             - layout.Section
             - layout.Page
-            - layout.Auto
+            - layout.SectionElement
+            - layout.ContentElement
+
+    - title: "Data models: docable"
+      desc: |
+        Classes representing python objects to be rendered.
+      contents:
+        - kind: "page"
+          path: "layouts-docable"
+          flatten: true
+          contents:
             - name: layout.Doc
               members: []
             - layout.DocFunction
@@ -93,50 +161,16 @@ quartodoc:
             - layout.DocClass
             - layout.Link
             - layout.Item
-            - layout.SectionElement
-            - layout.ContentElement
-
-
-website:
-  title: "quartodoc"
-  page-navigation: true
-  navbar:
-    left:
-      - file: get-started/overview.qmd
-        text: Get Started
-      - file: examples/
-        text: Examples
-      - href: api/
-        text: Reference
-    right:
-      - icon: github
-        href: https://github.com/machow/quartodoc/
-  sidebar:
-    - id: get-started
-      title: Get Started
-      style: floating
-      align: left
+            - layout.ChoicesChildren
+    - title: "Data models: docstring patches"
+      desc: |
+        Most of the classes for representing python objects live
+        in [](`griffe.dataclasses`) or [](`griffe.docstrings.dataclasses`).
+        However, the `quartodoc.ast` module has a number of custom classes to fill
+        in support for some important docstring sections.
       contents:
-        - get-started/overview.qmd
-        - section: "Basics"
-          contents:
-            - get-started/basic-docs.qmd
-            - get-started/crossrefs.qmd
-            - get-started/interlinks.qmd
-            - get-started/sidebar.qmd
-            - get-started/extending.qmd
-        - section: "Advanced"
-          contents:
-            - get-started/docstrings.qmd
-            - get-started/renderers.qmd
-            - get-started/building.qmd
-        - section: "Extra Topics"
-          contents:
-            - get-started/architecture.qmd
-
-
-format:
-  html:
-    theme: cosmo
-    css: styles.css
-    toc: true
+         - ast.DocstringSectionSeeAlso
+         - ast.DocstringSectionNotes
+         - ast.DocstringSectionWarnings
+         - ast.ExampleCode
+         - ast.ExampleText

docs/examples/index.qmd

@@ -1,14 +1,27 @@
+### Demo sites
+
 | style | source | layout |
 | ----- | ------ | ------ |
 | [pkgdown] | [github][pkgdown-code] | Index page with a title and short description for functions listed in each section. Each function gets its own documentation page. |
 | [single-page] | [github][sp-code] | Index page has function documentation embedded on it. |
-| [shiny] | [github][shiny-code] | The shiny docs translated to quartodoc, using a custom renderer. |
+
+### Packages using quartodoc
+
+
+| package | source | about |
+| ----- | ------ | ------ |
+| [siuba] | [github][sb-code] | Data analysis library. |
+| [shiny][shiny] |  | Dashboarding framework. |
+| [vetiver][vetiver] | [github][vt-code] | A tool to version, share, deploy and monitor ML models. |
 
 : {tbl-colwidths="[20, 20, 60]"}
 
 [pkgdown]: /examples/pkgdown/reference
 [pkgdown-code]: https://github.com/machow/quartodoc/tree/main/examples/pkgdown
 [single-page]: /examples/single-page/reference
 [sp-code]: https://github.com/machow/quartodoc/tree/main/examples/single-page
-[shiny]: /examples/shiny/reference
-[shiny-code]: https://github.com/machow/quartodoc/tree/main/examples/shiny
+[shiny]: https://shiny.rstudio.com/py/api/
+[vetiver]: https://rstudio.github.io/vetiver-python/stable/reference/
+[vt-code]: https://github.com/rstudio/vetiver-python
+[siuba]: https://siuba.org/api/
+[sb-code]: https://github.com/machow/siuba.org

docs/get-started/advanced-layouts.qmd

@@ -0,0 +1,14 @@
+---
+title: Advanced layouts
+jupyter:
+  kernelspec:
+    display_name: Python 3 (ipykernel)
+    language: python
+    name: python3
+---
+
+## Pages
+
+## Children options
+
+## 

docs/get-started/basic-building.qmd

@@ -0,0 +1,64 @@
+---
+title: Building and debugging docs
+jupyter:
+  kernelspec:
+    display_name: Python 3 (ipykernel)
+    language: python
+    name: python3
+---
+
+**tl;dr**: Once you've configured quartodoc in your `_quarto.yml` file, use the following commands to build and preview a documentation site.
+
+```bash
+# Create the documentation files. These are written 
+# by default to the reference/ folder in your docs.
+quartodoc build --verbose
+
+# Create optional inventory files, which allow you to
+# link to API doc pages within and across documentation
+# sites. These are put in the _inv folder in your docs.
+quartodoc interlinks
+
+# Preview the documentation site.
+# Use quarto render to generate the final site.
+quarto preview
+```
+
+## Rebuilding doc pages
+
+While using `quarto preview`, you can preview updates to your docstrings by regenerating their documentation pages:
+
+```bash
+quartodoc build --verbose
+```
+
+## Speeding up preview
+
+### Rewriting doc files
+
+By default, the `quartodoc build` only re-writes doc pages when it detects
+a change to their content. This helps prevent `quarto preview` from trying
+to re-render every doc page--including those that haven't changed.
+
+###  Selectively building doc pages
+
+Use the filter option with `quartodoc build` to generate a subset of doc pages.
+This is useful when you have a many (e.g. several hundred) doc pages, and want
+to test a change on a single page.
+
+```bash
+quartodoc build --filter 'get_object'
+```
+
+This option also accepts a wildcard pattern, which causes it to build docs for all matching objects.
+
+```bash
+# write the docs for the MdRenderer class, and any of its methods
+# (e.g. MdRenderer.renderer)
+quartodoc build --filter 'MdRenderer*'
+```
+
+:::{.callout-note}
+When using a name with a wildcard, be sure to put it in single quotes!
+Otherwise, your shell may try to "expand it" to match file names.
+:::