Docs render readme

Makefile

@@ -32,6 +32,17 @@ docs/examples/%: examples/%/_site
 
 docs-build-examples: docs/examples/single-page docs/examples/pkgdown docs/examples/auto-package
 
+docs-build-readme: export BUILDING_README = 1
+docs-build-readme:
+	# note that the input file is named GITHUB.qmd, because quart does not
+	# render files named README.qmd, and it is very cumbersome to work around
+	# this very strange behavior
+	cd docs \
+	  && quarto render GITHUB.qmd \
+	     --to gfm \
+		 --output README.md \
+		 --output-dir ..
+
 docs-build: docs-build-examples
 	cd docs && quarto add --no-prompt ..
 	cd docs && quartodoc build

README.md

@@ -1,108 +1,160 @@
+# Overview
 
-# quartodoc
+**quartodoc** lets you quickly generate Python package API reference
+documentation using Markdown and [Quarto](https://quarto.org). quartodoc
+is designed as an alternative to
+[Sphinx](https://www.sphinx-doc.org/en/master/).
 
-Generate python API documentation for quarto.
+Check out the below screencast for a walkthrough of creating a
+documentation site, or read on for instructions.
 
-## Install
+<p align="center">
+<a href="https://www.loom.com/share/fb4eb736848e470b8409ba46b514e2ed">
+<img src="https://cdn.loom.com/sessions/thumbnails/fb4eb736848e470b8409ba46b514e2ed-00001.gif" width="75%">
+</a>
+</p>
 
-    pip install quartodoc
+<br>
 
-Or for the latest changes:
+## Installation
 
-    python3 -m pip install -e git+https://github.com/machow/quartodoc.git#egg=quartodoc
-
-## Basic use
-
-``` python
-from quartodoc import get_function, MdRenderer
+``` bash
+python -m pip install quartodoc
+```
 
-# get function object ---
-f_obj = get_function("quartodoc", "get_function")
+or from GitHub
 
-# render ---
-renderer = MdRenderer(header_level = 1)
-print(
-    renderer.to_md(f_obj)
-)
+``` bash
+python -m pip install git+https://github.com/machow/quartodoc.git
 ```
 
-    # get_function
+<div>
 
-    `get_function(module: str, func_name: str, parser: str = 'numpy')`
+> **Install Quarto**
+>
+> If you haven’t already, you’ll need to [install
+> Quarto](https://quarto.org/docs/get-started/) before you can use
+> quartodoc.
 
-    Fetch a function.
+</div>
 
-    ## Parameters
-
-    | Name        | Type   | Description                | Default   |
-    |-------------|--------|----------------------------|-----------|
-    | `module`    | str    | A module name.             | required  |
-    | `func_name` | str    | A function name.           | required  |
-    | `parser`    | str    | A docstring parser to use. | `'numpy'` |
+## Basic use
 
-    ## Examples
+Getting started with quartodoc takes two steps: configuring quartodoc,
+then generating documentation pages for your library.
+
+You can configure quartodoc alongside the rest of your Quarto site in
+the
+[`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html)
+file you are already using for Quarto. To [configure
+quartodoc](https://machow.github.io/quartodoc/get-started/basic-docs.html#site-configuration),
+you need to add a `quartodoc` section to the top level your
+`_quarto.yml` file. Below is a minimal example of a configuration that
+documents the `quartodoc` package:
+
+``` yaml
+project:
+  type: website
+
+# tell quarto to read the generated sidebar
+metadata-files:
+  - _sidebar.yml
+
+
+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
+
+  sections:
+    - title: Some functions
+      desc: Functions to inspect docstrings.
+      contents:
+        # the functions being documented in the package.
+        # you can refer to anything: class methods, modules, etc..
+        - get_object
+        - preview
+```
 
-    ```python
-    >>> get_function("quartodoc", "get_function")
-    <Function('get_function', ...
-    ```
+Now that you have configured quartodoc, you can generate the reference
+API docs with the following command:
 
-## How it works
+``` bash
+quartodoc build
+```
 
-quartodoc consists of two pieces:
+This will create a `reference/` directory with an `index.qmd` and
+documentation pages for listed functions, like `get_object` and
+`preview`.
 
-- **collection**: using the library
-  [griffe](https://github.com/mkdocstrings/griffe) to statically collect
-  information about functions and classes in a program.
-- **docstring parsing**: also handled by griffe, which breaks it into a
-  tree structure.
-- **docstring rendering**: use plum-dispatch on methods like
-  MdRenderer.to_md to decide how to visit and render each piece of the
-  tree (e.g. the examples section, a parameter, etc..).
+Finally, preview your website with quarto:
 
-Here is a quick example of how you can grab a function from griffe and
-walk through it.
+``` bash
+quarto preview
+```
 
-``` python
-from griffe.loader import GriffeLoader
-from griffe.docstrings.parsers import Parser
+## Rebuilding site
 
-griffe = GriffeLoader(docstring_parser = Parser("numpy"))
-mod = griffe.load_module("quartodoc")
+You can preview your `quartodoc` site using the following commands:
 
-f_obj = mod._modules_collection["quartodoc.get_function"]
-```
+First, watch for changes to the library you are documenting so that your
+docs will automatically re-generate:
 
-``` python
-f_obj.name
+``` bash
+quartodoc build --watch
 ```
 
-    'get_function'
+Second, preview your site:
 
-``` python
-docstring = f_obj.docstring.parsed
-docstring
+``` bash
+quarto preview
 ```
 
-    [<griffe.docstrings.dataclasses.DocstringSectionText at 0x105a2c310>,
-     <griffe.docstrings.dataclasses.DocstringSectionParameters at 0x10f7961f0>,
-     <griffe.docstrings.dataclasses.DocstringSectionExamples at 0x10f7965b0>]
-
-Note that quartodoc’s MdRenderer can be called on any part of the parsed
-docstring.
-
-``` python
-from quartodoc import MdRenderer
-
-renderer = MdRenderer()
-
-print(
-    renderer.to_md(docstring[1])
-)
+## Looking up objects
+
+Generating API reference docs for Python objects involves two pieces of
+configuration:
+
+1.  the package name.
+2.  a list of objects for content.
+
+quartodoc can look up a wide variety of objects, including functions,
+modules, classes, attributes, and methods:
+
+``` yaml
+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
 ```
 
-    | Name        | Type   | Description                | Default   |
-    |-------------|--------|----------------------------|-----------|
-    | `module`    | str    | A module name.             | required  |
-    | `func_name` | str    | A function name.           | required  |
-    | `parser`    | str    | A docstring parser to use. | `'numpy'` |
+The functions listed in `contents` are assumed to be imported from the
+package.
+
+## Learning more
+
+Go [to the next
+page](https://machow.github.io/quartodoc/get-started/basic-docs.html) to
+learn how to configure quartodoc sites, or check out these handy pages:
+
+- [Examples
+  page](https://machow.github.io/quartodoc/examples/index.html): sites
+  using quartodoc.
+- [Tutorials
+  page](https://machow.github.io/quartodoc/tutorials/index.html):
+  screencasts of building a quartodoc site.
+- [Docstring issues and
+  examples](https://machow.github.io/quartodoc/get-started/docstring-examples.html):
+  common issues when formatting docstrings.
+- [Programming, the big
+  picture](https://machow.github.io/quartodoc/get-started/dev-big-picture.html):
+  the nitty gritty of how quartodoc works, and how to extend it.

docs/GITHUB.qmd

@@ -0,0 +1,9 @@
+---
+replace_base_domain: "https://machow.github.io/quartodoc"
+replace_rel_path: "/get-started"
+filters:
+  - _filters/replace-readme-links.lua
+format: gfm
+---
+
+{{< include get-started/overview.qmd >}}

docs/_filters/replace-readme-links.lua

@@ -0,0 +1,37 @@
+function Meta(meta)
+    replace_base_domain = tostring(meta.replace_base_domain[1].text)
+    replace_rel_path = tostring(meta.replace_rel_path[1].text)
+end
+
+-- pandoc Link object: replace the .qmd in the target with .html
+function Link(link)
+    -- replace .qmd with .html in target
+    -- replace beginning with replace_base_domain, accounting for / and ./ in paths
+    -- e.g. ./overview.qmd -> {replace_rel_path}/get-started/overview.html
+    -- e.g. /index.qmd -> {replace_base_domain}/index.html
+    -- e.g. https://example.com -> https://example.com
+    if link.target:match("%.qmd$") or link.target:match("%.qmd#.*$") then
+        link.target = link.target:gsub("%.qmd", ".html")
+        if link.target:match("^%./") then
+            link.target = link.target:gsub("^%./", replace_base_domain .. replace_rel_path .. "/")
+        end
+        if link.target:match("^/") then
+            link.target = link.target:gsub("^/", replace_base_domain .. "/")
+        end
+        -- if target does not start with http, do same as above
+        if not link.target:match("^http") then
+            link.target = replace_base_domain .. replace_rel_path .. "/" .. link.target
+        end
+    end
+
+    return link
+end
+
+return {
+    {
+        Meta = Meta
+    },
+    {
+        Link = Link
+    }
+}

docs/get-started/overview.qmd

@@ -13,10 +13,39 @@ jupyter:
 **quartodoc** lets you quickly generate Python package API reference documentation using Markdown and [Quarto](https://quarto.org).
 quartodoc is designed as an alternative to [Sphinx](https://www.sphinx-doc.org/en/master/).
 
+
 Check out the below screencast for a walkthrough of creating a documentation site, or read on for instructions.
 
+
+```{python}
+#| echo: false
+#| output: asis
+
+# this code ensures that the proper html for the tutorial screencast is used,
+# depending on whether it's being rendered for the github README, or doc site.
+import os
+
+if "BUILDING_README" in os.environ:
+    # I don't know why, but we need to repeat the Installation header here.
+    # or quarto makes it disappear when we generate the readme
+    print("""
+<p align="center">
+<a href="https://www.loom.com/share/fb4eb736848e470b8409ba46b514e2ed">
+<img src="https://cdn.loom.com/sessions/thumbnails/fb4eb736848e470b8409ba46b514e2ed-00001.gif" width="75%">
+</a>
+</p>
+
+<br>
+
+## Installation
+""")
+else:
+    print("""
 <div style="position: relative; padding-bottom: 64.5933014354067%; height: 0;"><iframe src="https://www.loom.com/embed/fb4eb736848e470b8409ba46b514e2ed?sid=31db7652-43c6-4474-bab3-19dea2170775" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
+<br>
+""")
 
+```
 
 ## Installation
 
@@ -41,7 +70,7 @@ If you haven't already, you'll need to [install Quarto](https://quarto.org/docs/
 
 Getting started with quartodoc takes two steps: configuring quartodoc, then generating documentation pages for your library.
 
-You can configure quartodoc alongside the rest of your Quarto site in the [`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html) file you are already using for Quarto.  To [configure quartodoc](basic-docs.qmd#site-configuration), you need to add a `quartodoc` section to the top level your `_quarto.yml` file.  Below is a minimal example of a configuration that documents the `quartodoc` package:
+You can configure quartodoc alongside the rest of your Quarto site in the [`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html) file you are already using for Quarto.  To [configure quartodoc](./basic-docs.qmd#site-configuration), you need to add a `quartodoc` section to the top level your `_quarto.yml` file.  Below is a minimal example of a configuration that documents the `quartodoc` package:
 
 ```yaml
 project:
@@ -128,9 +157,9 @@ The functions listed in `contents` are assumed to be imported from the package.
 
 ## Learning more
 
-Go [to the next page](./get-started/basic-docs.qmd) to learn how to configure quartodoc sites, or check out these handy pages:
+Go [to the next page](basic-docs.qmd) to learn how to configure quartodoc sites, or check out these handy pages:
 
-* [Examples page](./examples/index.qmd): sites using quartodoc.
-* [Tutorials page](./tutorials/index.qmd): screencasts of building a quartodoc site.
-* [Docstring issues and examples](./get-started/docstring-examples.qmd): common issues when formatting docstrings.
-* [Programming, the big picture](./get-started/dev-big-picture.qmd): the nitty gritty of how quartodoc works, and how to extend it.
+* [Examples page](/examples/index.qmd): sites using quartodoc.
+* [Tutorials page](/tutorials/index.qmd): screencasts of building a quartodoc site.
+* [Docstring issues and examples](./docstring-examples.qmd): common issues when formatting docstrings.
+* [Programming, the big picture](./dev-big-picture.qmd): the nitty gritty of how quartodoc works, and how to extend it.