Docstring > HTML generator that works with TD?

General TouchDesigner Discussion
1

Is there a way to generate HTML from docstrings that works with TDs module import system, that can handle imports of TD internal libraries as TDF/TDJSON?

Tried pdoc3 and it fails everywhere, e.g.

TDF = op.TDModules.mod.TDFunctions
NameError: name ‘op’ is not defined

2

+1 Currently stuck on this problem as well. Using sphinx and it’s failing on the same error: NameError: name 'op' is not defined

3

Just following up here on what I believe will be a solution, at least for my use case. As far as I’m aware, this solution is specific to Sphinx, the tool I’m using to generate html documentation from docstrings.

They key is to put the following at the top of your Sphinx conf.py file:

import sys
import mock
MOCK_MODULES = ['td', 'td.op']
for mod_name in MOCK_MODULES:
    sys.modules[mod_name] = mock.Mock()

This makes a “mock” of the td module so that it can be imported without error by Sphinx. Source for this solution here. (you will need to install the mock library for the above to work btw: ‘pip install mock’)

This mock solution only works however if you import the td module in your code. Here’s the import code in one of my extensions that doesn’t make pylint or TD upset (as far as I’m aware):

try:
    op
except NameError:
    from td import op, project, COMP, baseCOMP, ui # pylint:disable=import-error

The above is just an example of the imports I needed in one extension, with others usually only needing ‘op’ imported.

Hopefully this is helpful? Anyone got any better solutions?

1 Like
4

wow, thank you Ben! Finally managed to try this and it looks great with the readthedocs theme. But I’m running into an issue when bases classes are referenced via op.

class DisplayDeviceExt(op.Backend.mod.BaseExt.DeviceBaseExt)

In this case sphinx will not document my DisplayDevice class at all. Do you maybe have any idea how to fix this?

5

My understanding is the reason that that wont work, is because out side of touch, python doesn’t know how to resolve “mod” into you base class code. I’d try to define that base extension class in a way that python will understand without the td module in the same try/catch statement as before. For example If the “DeviceBaseEXT” module is in a module called base.py in the same folder as the module that defines your “DisplayDeviceEXT” class I would do something like this to wrap a proper import statement in the try/catch block:

try:
    op
    DeviceBaseExt = op.Backend.mod.BaseExt.DeviceBaseExt
except NameError:
    from td import op, project, COMP, baseCOMP, ui # pylint:disable=import-error
    from .base import DeviceBaseExt

Then instantiate your class with your new definition:

class DisplayDeviceExt(DeviceBaseExt)

6

thank you Ben. got it working