Including more content around generated API docs?

[h4l]

Hey, I mostly wanted to say thanks for quartodoc. I've recently been using it to build a docs site for a Python package of mine, and I've found the combination of Quarto and quartodoc to make a pleasant authoring experience, and (I hope) a good result for end-users. In particular, I like the way that quartodoc slots into a regular Quarto website as a single component, rather than being a tool that tries to take control over the whole documentation process. It makes for a flexible system that I feel confident I can tailor to my needs.

This is the docs site I made: https://h4l.github.io/v8serialize/en/latest/
Source for the docs: https://github.com/h4l/v8serialize/tree/main/docs

I've got a general question I'd appreciate advice on. When I was setting up the Reference section of my site, I tried out a few layouts before settling on the one I've used. The library has two main packages: v8serialize and v8serialize.jstypes. I've loosely arranged the reference pages around these two packages, but with pages covering the role of types/functions, like "API Constants" and "JavaScript Constants" which are part of the same package, but for different purposes. Another example is that there's a page for each category of JavaScript types like "Map & Set" and "Primitives".

I was wanting to be able to include more prose on these pages, for example on the Primitives page it would be nice to have a table showing the equivalent Python and JavaScript types. I was hoping to find a way to include a few paragraphs of .qmd markdown before the list of Python types/functions etc a reference page contains. Like a longer version of the summary.desc property of a page in the quartodoc config.

I tried using Quarto's {{ include ... >}} tag in the desc, but this didn't work out because the desc gets put into a markdown table (for the API doc index page), and Quarto won't allow complex stuff to be embedded within a table cell.

Another option would be to use a Python package-level doc comment, but then the page has a title containing the Python package name, and I'd need to make the package structure match the doc page structure, which I didn't really want to do.

Otherwise I think I could make it work by creating my own _sidebar.yml by hand, with my own .qmd files, and then using {{ include ... >}} to pull in the quartodoc generated pages into my wrapper pages.

I've not looked much into customising quartodoc with my own Python code, but I get the impression that I could write some Python to do pretty much anything. It would be nice if I've missed something and there's already a way to do this!

Or perhaps I should change how I'm thinking about the reference section, and keep the API docs more tied to packages, and write some separate more descriptive pages to complement them.

[machow]

Hey, are you saying you wanted to add more to pages like this?

[h4l]

Hey (sorry, I missed that you'd replied), that's right, I'd like to be able to put things there.