'Off-label' Usage Tips

[BradyAJohnston]

This is a bit left-of-field and the use case might be too off-label, so please let me know if that's the case!. I've been using quartodoc render the API docstrings for a Blender add-on (which I asked about in #130 and it has been working great).

I've since also been using it (and the underlying griffe) to make some other more atypical documentation, and I was wondering if anyone had any tips for how to potentially improve it.

Inside of Blender, you can do visual programming with drag-and-drop nodes. You can create custom nodes which is what I have done for my add-on. Inside of Blender you can add tool-tips and descriptions for the inputs & outputs, but there wasn't any easy way to make documentation for them.

Thanks to quartodoc I figured out a way to load in the data blocks for each node, match it with some additional descriptions and urls for example videos, and build nice .qmd pages that can then become part of the overall documentation site.

The resulting docs are here: https://bradyajohnston.github.io/MolecularNodes/nodes/topology.html

In the build script, I am manually assembling different bits of data from the additional documentation I have written that lives in a dictionary / json format, along with the information about types and tooltips from inside of the .blend file. I am assembling them as griffe docstrings then using the MdRenderer to step-wise render out the .qmd along with some custom breaks etc.

https://github.com/BradyAJohnston/MolecularNodes/blob/687d17b1a90328577860395e83de48c9a54b9c46/docs/build_node_docs.py

While this actually works quite well, and I am pretty happy with it, it's a bit of a cobbled-together mess. I was wondering if you have any tips for creating my own docstring class or something similar, that could hold the different aspects of the related information, rather than just putting them together in a list. Maybe there might even be a "oh you can just use this function / class" to make my life easier.

Again, this might be a bit too off-label, so please feel free to say I am on my own with this one.

[machow]

Ah, this is super interesting! One option is subclassing the MdRenderer, and using that directly in quartodoc. For example, the shiny team adds examples to their docs (like this one), by defining a subclass of the MdRenderer in and using that:

• Defining a renderer: https://machow.github.io/quartodoc/get-started/dev-renderers.html#defining-a-renderer
• Adding to quartodoc config.

edit: for example here is where their renderer checks if an example wasn't included. They add examples to their docstrings using this decorator that only inserts examples when they are building website docs.

[BradyAJohnston]

Thanks for all of the info! Looks like I might have a go at creating a MdRenderer subclass for these nodes. Reading through those examples you've link I think explains it, I'll see how I go!