Custom attributes to HTML templates

[silverbucket]

I would like to append the documentation with auxiliary data which would be collected at the time of document generation. (eg. test results).

Expected Behavior

When using pdoc3 programmatically, it would be nice if additional variables could be attached to the Class/Method objects, which could be accessed from within the templates.

Actual Behavior

Currently I'm unable to find any way to add custom variables.

Additional info

• pdoc version: 0.9.2

[kernc]

Can you show a full example how you'd use it?

pdoc.Class.obj points to the underlying type object. Module and Function likewise.

[silverbucket]

Thanks for that tip, (re: obj) it's what I needed to make further progress. What I'm currently doing is collecting pytest results and including them along-side the test suite documentation.

 # test_results contains dict of test results collected from pytest junit xml
context = pdoc.Context()
module = pdoc.Module('test/my_tests.py')
pdoc.link_inheritance(context)

for c in module.classes():
    for m in c.methods():
        m.obj.test_results = {}
        if m.refname in test_results:
            m.obj.test_results = test_results[m.refname]

print(module.html())

This is working fine for me now. I wonder if this is the supported approach, and if so perhaps an example could be added to the documentation (I'm willing to submit a PR if so).

Additionally, now that I'm using the programatic approach, filtering was no longer working. In the test suite I have a number of classes and methods set in __pdoc__ to be ignored. This worked fine when I used the command-line tool, I eventually got filtering working, though some warnings are being thrown and I'm not sure my approach is the best.

    context = pdoc.Context()
    module = pdoc.Module('test/my_tests.py')
    pdoc.link_inheritance(context)

    def filter_objects(obj):
        if obj.refname.replace('my_tests.', '') in module.__pdoc__:
            return False
        return True

    for c in module.classes():
        for m in c.methods():
            m.obj.test_results = {}
            if m.refname in test_results:
                m.obj.test_results = test_results[m.refname]

    print(pdoc.html(module, docfilter=filter_objects))

This works, however I get the warnings:

.../venv/lib/python3.8/site-packages/pdoc/__init__.py:782: UserWarning: __pdoc__-overriden key 'client' does not exist in module 'my_tests'
  warn('__pdoc__-overriden key {!r} does not exist '
.../venv/lib/python3.8/site-packages/pdoc/__init__.py:782: UserWarning: __pdoc__-overriden key 'BasicTest' does not exist in module 'my_tests
  warn('__pdoc__-overriden key {!r} does not exist '

Both client and BasicTest are two items that are set to be ignored.

While currently I'm just working with one file, I wonder how well this implementation will scale as more test files are added. Any input welcome, and I'd be happy to help improve the documentation on this procedure once I'm confident in the approach.

[kernc]

You need to pass the context instance to modules you create:

module = pdoc.Module(..., context=context)

Other than that, I don't see why module's __pdoc__ would be ignored.

[silverbucket]

@kernc Ah, of course - I had this originally added but must have removed it without noticing during experimentation. Re-adding context solves the issue of filtering. I've created a small PR mentioning the availability of the obj property, for your consideration in merging. (Would have saved me some time in getting started with custom templates).