Open silverbucket opened 3 years ago
Can you show a full example how you'd use it?
pdoc.Class.obj
points to the underlying type
object. Module
and Function
likewise.
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.
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.
@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).
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
0.9.2