defextract_toc(text: str)

Expand source codeBrowse 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 intext.

defformat_git_link(template: str, dobj: Doc)

Expand source codeBrowse 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

Interpolatetemplate as a formatted string literal using values extractedfromdobj and the working environment.

defglimpse(text: str, max_length=153, *, paragraph=True)

Expand source codeBrowse 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.Ifparagraph is True, the first paragraph will be returned,but never longer thanmax_length characters.

defminify_css(css: str)

Expand source codeBrowse 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.

defminify_html(html: str)

Expand source codeBrowse 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.

defto_html(text: str,
*,
docformat: str | None = None,
module: Module | None = None,
link: Callable[..., str] | None = None,
latex_math: bool = False)

Expand source codeBrowse 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 oftext interpreted asdocformat.__docformat__ is respectedif present, otherwise Numpydoc and Google-style docstrings are assumed,as well as pure Markdown.

module should be the documented module (so the references can beresolved) andlink is the hyperlinking function like the one in theexample template.

defto_markdown(text: str,
*,
docformat: str | None = None,
module: Module | None = None,
link: Callable[..., str] | None = None)

Expand source codeBrowse 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

Returnstext, assumed to be a docstring indocformat, converted to markdown.__docformat__ is respectedif present, otherwise Numpydoc and Google-style docstrings are assumed,as well as pure Markdown.

module should be the documented module (so the references can beresolved) andlink is the hyperlinking function like the one in theexample template.

Classes

classReferenceWarning(*args, **kwargs)

Expand source codeBrowse 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 into_html() when a object reference in markdowndoesn'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