mitmproxy / mitmproxy/pdoc

Can't combine math and custom filter

Open
#772 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
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:
  1. Create following module file hello.py:
"""
foo bar baz
"""

def foo():
	"""
	foo bar baz
	"""
	return 0
  1. Create following script make_doc.py to 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'))
  1. Create pdoc_templates directory with the following files:
  • math.html.jinja2, copied from source with no modifications
  • module.html.jinja2 with 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 %}
  1. Run make_doc.py and check the output, which uses FoO instead of foo, as intended.
  2. Uncomment the line in make_doc.py with math = True.
  3. Run make_doc.py again. The output now uses fooeverywhere, implying that myfilter was ignored.
System Information

15.0.1

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.