docs: add quartodoc site setup

[nealrichardson]

This is currently pretty terrible, but it renders something.

[github-actions]

☂️ Python Coverage

current status: ✅

Overall Coverage

Lines	Covered	Coverage	Threshold	Status
589	511	87%	80%	🟢

New Files

No new covered files...

Modified Files

No covered modified files...

updated for commit: 992bf0d by action🐍

[machow]

Hey, happy to take a look! I think there are two big things to mention right out of the gate:

• Previews. For PRs on tools like Great Tables and py-shiny, we use a github deployment to push a preview of the docs.
  • We just use netlify previews (e.g. https://pr-249--gt-python.netlify.app).
  • Fast to set up, and happy to pair on it.
  • Here's the gh action task quartodoc uses to push previews
• Reference Index Structure. I've noticed a few strategies for laying out classes/funcs on the index page.
  • Every package seems to do things differently, and I'm super interested in the design aspect of this.
  • I tried to capture a couple of the strategies below.

Reference Index Structure Strategies

Flat index

Classes and their methods are listed flat on the index page. E.g.

- name: connect.Client
  members: []
- connect.Client.connect_version
- connect.Client.me

This makes everything easy to find from the index. But only really works for packages that want to spotlight a few classes and their methods.

For example, pins-python documents functions for creating a BaseBoard class, and then the methods on BaseBoard classes. Note that it doesn't even document pins.BaseBoard itself.

Similarly, Great Tables has one main class (GT), so flattens the methods. Notice that GT methods aren't laid out in one big sections, but split across sections. Sections are ordered out based on how common the task is through to be.

Methods on classes

Methods are documented on their classes. This is useful when there aren't 1 or 2 main classes, or just a bunch of classes.

This is the style your docs are currently using. It's also done in places by py-shiny, which has a million functions and only a few classes (which aren't really the main entry point anyway).

Page entries (collapsing sections)

When you have a ton of extra stuff, or less useful stuff to document, you can make a page entry. This will create only a single item in the API Reference, but that item might open up to a page with a bunch of classes, etc..

For example, here is a line in its quartodoc where py-shiny creates a Page of Miscellaneous Types.

Note that clicking into Miscellaneous Types opens to a bunch of classes most users likely don't care about. But they get linked to from the type annotations of other functions, so I think they shiny team wanted people to be able to click the interlinks and get to docs on various types.

Another good example is ibis, which doesn't use a reference index. Instead, a dropdown links to pages of documented classes/methods.