diff --git a/Makefile b/Makefile
index 0dfc94b8..0c1e7659 100644
--- a/Makefile
+++ b/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
diff --git a/README.md b/README.md
index 22a5130e..9c457a36 100644
--- a/README.md
+++ b/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
+
+
+
+
+
- pip install quartodoc
+
-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
+
- `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.
+
- ## 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")
- ,
- ,
- ]
-
-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.
diff --git a/docs/GITHUB.qmd b/docs/GITHUB.qmd
new file mode 100644
index 00000000..8510815b
--- /dev/null
+++ b/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 >}}
diff --git a/docs/_filters/replace-readme-links.lua b/docs/_filters/replace-readme-links.lua
new file mode 100644
index 00000000..c7c9dac8
--- /dev/null
+++ b/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
+ }
+}
diff --git a/docs/get-started/overview.qmd b/docs/get-started/overview.qmd
index 3f6d780f..e9a8ec24 100644
--- a/docs/get-started/overview.qmd
+++ b/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("""
+
+
+
+
+
+
+
+
+## Installation
+""")
+else:
+ print("""
+
+""")
+```
## 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.
\ No newline at end of file
+* [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.