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 from dobj 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 than max_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 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.

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 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.

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