Rendering docs without loading the package

[BradyAJohnston]

This is a strange case, so if it's way outside of the realm of intended use cases for quartodoc then let me know, and I'll try a different approach. It will require a little bit of extra explanation as to why things are this way / why they aren't straightforward.

I'm the developer of an add-on for the 3D animation software Blender. The add-on is for the import and animation of molecular and structural biology data and is called Molecular Nodes.

The addon is structured mostly like a regular Python package, but it calls a number of functions from the bpy package, which only ships with Blender, and thus the code can only be run internally inside of the Python distribution that ships with Blender. This has its own issues with being able to set up testing suites etc, but I don't get into that here.

Currently I build the documentation website for the add-on with Quarto form a series of .md files. This explains how to install and use the addon, but doesn't document any of the docstrings of the python code that runs under the hood. All of the documentation is currently hand-made for the addon, which mostly covers the GUI aspects of how to use it.

I would also like to have a page / series of pages on the python API that for the add-on so that others can potentially create scripts that leverage the code that is already written. I would like to auto-generate this documentation and ideally want to use Quarto to render it all. I've tried out quartodoc, but I can't get it to work as I get the errors:

ModuleNotFoundError: MolecularNodes

This is likely down to the quirkiness of developing stuff that can only run inside of Blender and the bundled python. I have also tried installing quartodoc inside of the bundled python and running it that way but I run into similar problems, so I figure doing it the straight-forward way likely won't work.

Is there a way to use quartodoc (or another tool) to just generate .md files from a series of .py files that contain functions and docstrings, without loading the modules themselves? I can then use these along with the other .md files and Quarto to generate the website.

[machow]

Hey, are you saying the code you want to document is not inside an installed package, but inside a folder somewhere? I think you can import it in this case, by putting it on sys.path.

I've added a PR (#131) with an option in the config called source_dir that lets you add things to sys.path. Do you mind trying it to see if it works for your use case?

sys.path example

For example, if you have a file named /path/to/code/some_module.py:

def some_function():
    """A function defined in a random python script"""

Then, you should be able to import it using...

import sys
from quartodoc import Auto, blueprint, preview

sys.path.append("/path/to/code/")

# the documentation object quartodoc would load from your config
doc = blueprint(Auto(name="some_module.some_function"))

# a nice preview of it
preview(doc)

Using source_dir argument

In _quarto.yml now you should be able to do something like...

# quarto stuff ----------------------------------------------------------------
project:
  type: website

website:
  title: weird-install example
  navbar:
    left:
      - file: reference/index.qmd
        text: "Reference"

# quartodoc -------------------------------------------------------------------

quartodoc:
  package: null

  # NOTE: here's the source_dir argument! ----
  # it is expanded relative to _quarto.yml, but you can also
  # use a relative path: /path/to/src
  source_dir: ./src

  sections:
    - title: Some functions
      desc: These functions inspect and parse docstrings.
      contents:
        - some_module.some_function

[BradyAJohnston]

I've just downloaded and tested the branch, and it works perfectly! Thanks so much for the prompt reply and feature implementation.

I tested with the custom python code and also use in _quarto.yml and both work great for generating the docs.

[filipwastberg]

Amazing! I was looking for exactly this.