Module pdoc.html_helpers
Helper functions for HTML output.
Functions
def extract_toc(text: str)
-
Expand source code Browse git
def extract_toc(text: str): """ Returns HTML Table of Contents containing markdown titles in `text`. """ with _fenced_code_blocks_hidden(text) as result: result[0] = _ToMarkdown.DOCTESTS_RE.sub('', result[0]) text = result[0] toc, _ = _md.reset().convert(f'[TOC]\n\n@CUT@\n\n{text}').split('@CUT@', 1) if toc.endswith('<p>'): # CUT was put into its own paragraph toc = toc[:-3].rstrip() return toc
Returns HTML Table of Contents containing markdown titles in
text
. def format_git_link(template: str, dobj: Doc)
-
Expand source code Browse git
def format_git_link(template: str, dobj: pdoc.Doc): """ Interpolate `template` as a formatted string literal using values extracted from `dobj` and the working environment. """ if not template: return None try: if 'commit' in _str_template_fields(template): commit = _git_head_commit() obj = pdoc._unwrap_descriptor(dobj) abs_path = inspect.getfile(inspect.unwrap(obj)) path = _project_relative_path(abs_path) # Urls should always use / instead of \\ if os.name == 'nt': path = path.replace('\\', '/') lines, start_line = inspect.getsourcelines(obj) start_line = start_line or 1 # GH-296 end_line = start_line + len(lines) - 1 url = template.format(**locals()) return url except Exception: warn(f'format_git_link for {obj} failed:\n{traceback.format_exc()}') return None
Interpolate
template
as a formatted string literal using values extracted fromdobj
and the working environment. def glimpse(text: str, max_length=153, *, paragraph=True)
-
Expand source code Browse git
def glimpse(text: str, max_length=153, *, paragraph=True, _split_paragraph=partial(re.compile(r'\s*\n\s*\n\s*').split, maxsplit=1), _trim_last_word=partial(re.compile(r'\S+$').sub, ''), _remove_titles=partial(re.compile(r'^(#+|-{4,}|={4,})', re.MULTILINE).sub, ' ')): """ Returns a short excerpt (e.g. first paragraph) of text. If `paragraph` is True, the first paragraph will be returned, but never longer than `max_length` characters. """ text = text.lstrip() if paragraph: text, *rest = _split_paragraph(text) if rest: text = text.rstrip('.') text += ' …' text = _remove_titles(text).strip() if len(text) > max_length: text = _trim_last_word(text[:max_length - 2]) if not text.endswith('.') or not paragraph: text = text.rstrip('. ') + ' …' return text
Returns a short excerpt (e.g. first paragraph) of text. If
paragraph
is True, the first paragraph will be returned, but never longer thanmax_length
characters. def minify_css(css: str)
-
Expand source code Browse git
@lru_cache() def minify_css(css: str, _whitespace=partial(re.compile(r'\s*([,{:;}])\s*').sub, r'\1'), _comments=partial(re.compile(r'/\*.*?\*/', flags=re.DOTALL).sub, ''), _trailing_semicolon=partial(re.compile(r';\s*}').sub, '}')): """ Minify CSS by removing extraneous whitespace, comments, and trailing semicolons. """ return _trailing_semicolon(_whitespace(_comments(css))).strip()
Minify CSS by removing extraneous whitespace, comments, and trailing semicolons.
def minify_html(html: str)
-
Expand source code Browse git
def minify_html(html: str, _minify=partial( re.compile(r'(.*?)(<pre\b.*?</pre\b\s*>)|(.*)', re.IGNORECASE | re.DOTALL).sub, lambda m, _norm_space=partial(re.compile(r'\s\s+').sub, '\n'): ( _norm_space(m.group(1) or '') + (m.group(2) or '') + _norm_space(m.group(3) or '')))): """ Minify HTML by replacing all consecutive whitespace with a single space (or newline) character, except inside `<pre>` tags. """ return _minify(html)
Minify HTML by replacing all consecutive whitespace with a single space (or newline) character, except inside
<pre>
tags. def to_html(text: str,
*,
docformat: str | None = None,
module: Module | None = None,
link: Callable[..., str] | None = None,
latex_math: bool = False)-
Expand source code Browse git
def to_html(text: str, *, docformat: Optional[str] = None, module: Optional[pdoc.Module] = None, link: Optional[Callable[..., str]] = None, latex_math: bool = False): """ Returns HTML of `text` interpreted as `docformat`. `__docformat__` is respected if present, otherwise Numpydoc and Google-style docstrings are assumed, as well as pure Markdown. `module` should be the documented module (so the references can be resolved) and `link` is the hyperlinking function like the one in the example template. """ # Optionally register our math syntax processor if not latex_math and _MathPattern.NAME in _md.inlinePatterns: _md.inlinePatterns.deregister(_MathPattern.NAME) elif latex_math and _MathPattern.NAME not in _md.inlinePatterns: _md.inlinePatterns.register(_MathPattern(_MathPattern.PATTERN), _MathPattern.NAME, _MathPattern.PRIORITY) md = to_markdown(text, docformat=docformat, module=module, link=link) return _md.reset().convert(md)
Returns HTML of
text
interpreted asdocformat
.__docformat__
is respected if present, otherwise Numpydoc and Google-style docstrings are assumed, as well as pure Markdown.module
should be the documented module (so the references can be resolved) andlink
is the hyperlinking function like the one in the example template. def to_markdown(text: str,
*,
docformat: str | None = None,
module: Module | None = None,
link: Callable[..., str] | None = None)-
Expand source code Browse git
def to_markdown(text: str, *, docformat: Optional[str] = None, module: Optional[pdoc.Module] = None, link: Optional[Callable[..., str]] = None): """ Returns `text`, assumed to be a docstring in `docformat`, converted to markdown. `__docformat__` is respected if present, otherwise Numpydoc and Google-style docstrings are assumed, as well as pure Markdown. `module` should be the documented module (so the references can be resolved) and `link` is the hyperlinking function like the one in the example template. """ if not docformat: docformat = str(getattr(getattr(module, 'obj', None), '__docformat__', 'numpy,google ')) docformat, *_ = docformat.lower().split() if not (set(docformat.split(',')) & {'', 'numpy', 'google'}): warn(f'__docformat__ value {docformat!r} in module {module!r} not supported. ' 'Supported values are: numpy, google.') docformat = 'numpy,google' with _fenced_code_blocks_hidden(text) as result: text = result[0] text = _ToMarkdown.admonitions(text, module) if 'google' in docformat: text = _ToMarkdown.google(text) text = _ToMarkdown.doctests(text) text = _ToMarkdown.raw_urls(text) # If doing both, do numpy after google, otherwise google-style's # headings are incorrectly interpreted as numpy params if 'numpy' in docformat: text = _ToMarkdown.numpy(text) if module and link: # Hyperlink markdown code spans not within markdown hyperlinks. # E.g. `code` yes, but not [`code`](...). RE adapted from: # https://github.com/Python-Markdown/markdown/blob/ada40c66/markdown/inlinepatterns.py#L106 # Also avoid linking triple-backticked arg names in deflists. linkify = partial(_linkify, link=link, module=module, wrap_code=True) text = re.sub(r'(?P<inside_link>\[[^\]]*?)?' r'(?:(?<!\\)(?:\\{2})+(?=`)|(?<!\\)(?P<fence>`+)' r'(?P<code>.+?)(?<!`)' r'(?P=fence)(?!`))', lambda m: (m.group() if m.group('inside_link') or len(m.group('fence')) > 2 else linkify(m)), text) result[0] = text text = result[0] return text
Returns
text
, assumed to be a docstring indocformat
, converted to markdown.__docformat__
is respected if present, otherwise Numpydoc and Google-style docstrings are assumed, as well as pure Markdown.module
should be the documented module (so the references can be resolved) andlink
is the hyperlinking function like the one in the example template.
Classes
class ReferenceWarning (*args, **kwargs)
-
Expand source code Browse git
class ReferenceWarning(UserWarning): """ This warning is raised in `to_html` when a object reference in markdown doesn't match any documented objects. Look for this warning to catch typos / references to obsolete symbols. """
This warning is raised in
to_html()
when a object reference in markdown doesn't match any documented objects.Look for this warning to catch typos / references to obsolete symbols.
Ancestors
- builtins.UserWarning
- builtins.Warning
- builtins.Exception
- builtins.BaseException