Can't combine math and custom filter
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 2.5k
- Forks
- 228
- PR merge metrics
- No merged PRs in 30d
Description
This may be a bug, or just me doing it wrong, but I don't know which.
Problem Description
I am able to implement custom filters to my docstrings using pdoc.render.env.filters, but these filters stop working if I ask for math mode.
Steps to reproduce the behavior:
- Create following module file
hello.py:
"""
foo bar baz
"""
def foo():
"""
foo bar baz
"""
return 0
- Create following script
make_doc.pyto generate documentation:
import pdoc
print(pdoc.__version__) # prints out "15.0.1"
def myfilter(txt):
out = txt.replace('foo', 'FoO')
return out
pdoc.render.env.filters['myfilter'] = myfilter
pdoc.render.configure(template_directory = 'pdoc_templates')
# pdoc.render.configure(math = True)
with open('index.html', 'w') as fid:
fid.write(pdoc.pdoc('hello'))
- Create
pdoc_templatesdirectory with the following files:
math.html.jinja2, copied from source with no modificationsmodule.html.jinja2with the following contents:
{% extends "default/module.html.jinja2" %}
{% macro docstring(var) %}
{% if var.docstring %}
<div class="docstring">{{ var.docstring | to_markdown | myfilter | to_html | linkify(namespace=var.qualname) }}</div>
{% endif %}
{% endmacro %}
- Run
make_doc.pyand check the output, which usesFoOinstead offoo, as intended. - Uncomment the line in
make_doc.pywithmath = True. - Run
make_doc.pyagain. The output now usesfooeverywhere, implying thatmyfilterwas ignored.
System Information
15.0.1
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with make_doc.py and the pdoc.render.configure(math=True) path, then compare how pdoc_templates/module.html.jinja2 is processed with and without math mode. Trace the custom filter registration through pdoc.render.env.filters and inspect math.html.jinja2. Done means myfilter still affects the rendered docstrings when math mode is enabled, while the documented math rendering remains intact.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100