pdoc
pdoc copied to clipboard
pdoc3
Long latex formulars in inherited members are abbreviated in a wrong way
Expected Behavior
All latex formulars are shown correctly, or be abbreviated correctly.
Actual Behavior
Long latex formulas from ancestor classes are not shown correctly. It depends on the length of the formular, short formulars are not abbreviated and represended correctly.
Steps to Reproduce
class Material(object):
""" Stores material data """
C: float
D: float
E: float
F: float
def __init__(self):
self.C = 0
r"""
6x6 material stiffness matrix
.. math::
C = \begin{bmatrix}
C_{11} & C_{12} & C_{13} & 0 & 0 & 0 \\
C_{12} & C_{22} & C_{23} & 0 & 0 & 0 \\
C_{13} & C_{23} & C_{33} & 0 & 0 & 0 \\
0 & 0 & 0 & C_{44} & 0 & 0 \\
0 & 0 & 0 & 0 & C_{55} & 0 \\
0 & 0 & 0 & 0 & 0 & C_{66}
\end{bmatrix}
"""
self.D = 0
r"""
2x3 material stiffness matrix
.. math::
D =
\begin{bmatrix}
D_{11} & D_{12} & D_{13} \\
D_{12} & D_{22} & D_{23} \\
\end{bmatrix}
"""
self.E = 0
r"""
2x3 material stiffness matrix
.. math::
E = \begin{bmatrix}
E_{11} & E_{12} & E_{13} \\
E_{12} & E_{22} & E_{23} \\
\end{bmatrix}
"""
self.F = 0
r"""
2x3 material stiffness matrix
.. math::
F =
\begin{bmatrix}
F_{11} & F_{12} & F \\
F_{12} & F_{22} & F_{23} \\
\end{bmatrix}
"""
class Composite(Material):
"""
Stores material data for a composite material
"""
with my module named core
pdoc --html core -c latex_math=True -c show_inherited_members=True -f
Additional info
- pdoc version: 0.8.4
If anyone has the same issue, a quick workaround is by not shortening the inherited descriptions:
Inherited descriptions are shortened to default max_length of 153 in
https://github.com/pdoc3/pdoc/blob/04960e41b9bb598b664a50078f4c233817326170/pdoc/html_helpers.py#L48-L51
Which is used in the html template https://github.com/pdoc3/pdoc/blob/04960e41b9bb598b664a50078f4c233817326170/pdoc/templates/html.mako#L52
A simple workaround is to use a modified template and set the max length to float('inf') or something big like 9999999 to avoid shortening the description
docstring = glimpse(d.docstring, max_length=float('inf')) if short or inherits else d.docstring
I don't see how the seemingly erroneous output can be easily remedied – the paragraph strings are too long and get truncated to the absolute specified size.
To avoid overriding the whole HTML template, this might be a good fit for a config.mako tunable.
A simple workaround is to use a modified template and set the max length to
float('inf')or something big like 9999999 to avoid shortening the description
Another workaround might be to override just the glimpse() function by specifying its implementation in a config.mako template:
## config.mako:
<%!
...
from pdoc.html_helpers import glimpse as _glimpse
def glimpse(text, *args, **kwargs):
return _glimpse(text, max_length=9999999, paragraph=False)
%>