thanks, i made it in quartodoc

isabel zimmerman, posit pbc

there’s of course– many ways to talk about documentation. you can learn how to write accessible explanations to technical terms, how to build reproducible examples…

i am a open source software engineer at posit, and that role makes me think of everything as a tooling problem, and docs is no exception. the R ecosytem has a well loved tool – pkgdown is a tool used to scaffold documentation, and it is massively loved in R community bc of its predictability & straightforward structure. if youre in the R world, you might not even realize all the benefits you have

users benefit from package down since there is a predictable structure: landing page, reference, articles, news, and maybe a getting started. developers can make a packagedown site in about 1 minute (jenny bryan said this is possible, and i believe it was confirmed in an earlier talk that we can, in fact, trust jenny bryan).

i have to say, in contrast to the well-engineered, straightforward choice in R, the python world feels like the wild west. when i started building the package vetiver, i really struggled to find a tool that felt that felt just right to create documentation websites.

in fact, i felt a bit like goldilocks…

if you’re not familiar with the tale, goldilocks is a children’s story of a young girl who is lost in the woods and finds a house where no one is home, walks in, and starts messing with the homeowners stuff.

she is hungry and tries out 3 bowls of porridge that are set out on the table: the first one is freezing cold

the next is scorching hot,

and the last is just right

she ends up messing around with a bunch of other stuff in this house and then some HOMEOWNING BEARS come in and she realizes it was bears that inhabited the home, but they …

allegedly live happily ever after.

while goldilocks legally might have been breaking and entering, we’re going to view this tale with the child-like lens where goldilocks has entered a strange new place and she believes this world has been made for her, but she often feels frustrated because she knows what she wants, but oftentimes nothing feels just right.

when i started making my first docs site, i felt this frustration of knowing what i wanted in my docs– i wanted a maintainable, markdown based documentation system that would give usesrs all the information they needed to be successful! and, if we’re talking about docs utopia…ideally, this tool would be super easy to use, have minimal other extensions necessary, and just overall allow me to spend more time on the content of the site rather than fiddling with all these settings

but the tools at hand not feeling just right

long format docs

…when and why to run the code

i knew i wanted long format documentation

the r world has this down to a science, in fact, they have a name (vignettes) and vignettes are great for a telling a story, giving context to a small workflow your package can help with!

long format docs

so i tried a tool built for long format documentation called mkdocs. it was great to get started, and i was able write in markdown, which was exactly what i wanted! but i realized, users cannot live on vignettes alone…. were fantastically prepared to know WHEN, but not HOW to use the vetiver package. they needed something else too–not just long format

this documentation tool was not just right, it was way too much information for users

function reference

…how to run code

function reference

okay, so in python, when you write out source code for packages, you write something called a docstring. these are available so users can see in your code how to use your functions!

and theres special ways to format them– you can see here i have indented stuff in a special way, done some special triple quotation marks, whatnot.

function reference

i knew there were tools out there that could progrmmatically export this information to a beautiful website page, called a function reference (or api documentation, referring to the fact it is documenting your packages API)

i have the function name up top, a function signature, you can see this bulleted point list of parameters, and if you scroll down theres examples and such

and i found a tool for just this, called sphinx!!! it took my code, and spit out restructured text

function reference

but in true goldilocks…maybe goldiDOCS fashion…this function reference alone was not just right– API docs were not enough. while sphinx did allow for me to have what i needed for the generated website, i really wanted to have a markdown based site, not restructured text, and i didn’t want to continue to wrangle all the extensions i had to add on to make the website i had. for this goldilocks and this project, sphinx was not enough.

so my quest for the just right docs framework continued.

quartodoc 🤎

one of my colleagues, michael chow, who works on the quarto team, tuned me into a project he was working on.

quartodoc is a python package that generates a function reference page for your quarto website.

quarto is a publishing framework…

quartodoc 🤎

i was able to get beautiful api docs

and in the quartodoc world, i have a lot of sphinx similarities–a few differences is that, out of the box, i get my parameters as a table rather than a bulleted list, with columns such as type and default

quartodoc 🤎

and i was able to leverage the markdown native format of quarto, which was built for writing technical documentation

developer wins

quick to get started

pip install quartodoc

(little bit of configuration)

quartodoc build
quartodoc preview

little bit of configuration

_quarto.yml

project:
  type: website

metadata-files:
  - _sidebar.yml

quartodoc:
  title: Reference
  sidebar: _sidebar.yml
  package: goldilocks
  sections:
    - title: My golden functions
      desc: These functions are just right!
      contents:
        - house_function
        - Goldilocks.eat_porridge
        - Goldilocks.take_nap

built to be quick to get started

looks and feels like a bullet point list of what you want on your website, this literate layout is maintainable

little bit of configuration

_quarto.yml

project:
  type: website

metadata-files:
  - _sidebar.yml

quartodoc:
  title: Reference
  sidebar: _sidebar.yml
  package: goldilocks
  sections:
    - title: My golden functions
      desc: These functions are just right!
      contents:
        - house_function
        - Goldilocks.eat_porridge
        - Goldilocks.take_nap

start with a yaml chunk that is quartodoc specific

little bit of configuration

_quarto.yml

project:
  type: website

metadata-files:
  - _sidebar.yml

quartodoc:
  title: Reference
  sidebar: _sidebar.yml
  package: goldilocks
  sections:
    - title: My golden functions
      desc: These functions are just right!
      contents:
        - house_function
        - Goldilocks.eat_porridge
        - Goldilocks.take_nap

tell quartodoc that you would like it to create a sidebar (quartodoc will output this in a file called _sidebar.yml, you won’t ever have to touch it if you dont want)

little bit of configuration

_quarto.yml

project:
  type: website

metadata-files:
  - _sidebar.yml

quartodoc:
  title: Reference
  sidebar: _sidebar.yml
  package: goldilocks
  sections:
    - title: My golden functions
      desc: These functions are just right!
      contents:
        - house_function
        - Goldilocks.eat_porridge
        - Goldilocks.take_nap

package you would like to document (it must be installed)

little bit of configuration

_quarto.yml

project:
  type: website

metadata-files:
  - _sidebar.yml

quartodoc:
  title: Reference
  sidebar: _sidebar.yml
  package: goldilocks
  sections:
    - title: My golden functions
      desc: These functions are just right!
      contents:
        - house_function
        - Goldilocks.eat_porridge
        - Goldilocks.take_nap

generate an index page, which will be a scrollable list of functions, separating

little bit of configuration

_quarto.yml

project:
  type: website

metadata-files:
  - _sidebar.yml

quartodoc:
  title: Reference
  sidebar: _sidebar.yml
  package: goldilocks
  sections:
    - title: My golden functions
      desc: These functions are just right!
      contents:
        - house_function
        - Goldilocks.eat_porridge
        - Goldilocks.take_nap

add in what you would like to document

if you add a class, all the methods and attributes are autodocumented on each page, but you can also split it out like i did for Goldilocks class here

little bit of configuration

these 17 lines of configuration will generate a site that will include this reference page

website built with quarto

• generates .qmd files as reference pages
• accessibility built in
• extensible as packages grow

able to write in markdown

comes with high contrast highlighting, accessible sizing, and easily customizable alt text for images etc

quarto able to grow from 1 page to large sites…vetiver is a pretty simple website… but

extensibility

and to really highlight extensibility–a python data science package called ibis just moved their documentation to quartodoc, you can see here they’ve added some custom code formatting and really fun table highlighting to make the table colors match the code highlighting

this was something they developed inside of quartodoc to be able to customize their docs to be JUST RIGHT for them!

user wins

predictable

• highlighted things
• story of R -> Python

quartodoc leans on the lessons learned from packagedown and starts users off with a simple site outline built to make things easy to find, allowing developers to worry about content, not how to set up their site

WASM elements

and if you’d like to make even MORE complex documentation, the shiny docs

thank you to michael chow for quartodoc (and emil hvitfeldt for the slide help!)

questions @ pos.it/slido-cd

i have been a delighted user of quartodoc. i have to say a heartfelt thank you michael chow from the quarto team at posit who has done all this amazing work to make my life easier.

goldilocks, in our lens, is a hospitality story– where goldilocks was lost, she found a home in quartodoc that felt just right.