Skip to content

Commit

Permalink
Merge pull request #311 from davfsa/bugfix/296-hyperlinks-pointing-to…
Browse files Browse the repository at this point in the history
…-index

Dont document index.html in the index
  • Loading branch information
davfsa authored Oct 13, 2020
2 parents e77eb0e + f2425af commit c8d88c8
Showing 1 changed file with 70 additions and 0 deletions.
70 changes: 70 additions & 0 deletions docs/patched_pdoc.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,77 @@
# -*- coding: utf-8 -*-
def main():
import json
import os.path as path
import re
from functools import lru_cache

import pdoc
from pdoc import cli

# We don't document stuff on the index of the documentation, but pdoc doesn't know that,
# so we have to patch the function that generates the index.
def _patched_generate_lunr_search(top_module, index_docstrings, template_config):
def trim_docstring(docstring):
return re.sub(
r"""
\s+| # whitespace sequences
\s+[-=~]{3,}\s+| # title underlines
^[ \t]*[`~]{3,}\w*$| # code blocks
\s*[`#*]+\s*| # common markdown chars
\s*([^\w\d_>])\1\s*| # sequences of punct of the same kind
\s*</?\w*[^>]*>\s* # simple HTML tags
""",
" ",
docstring,
flags=re.VERBOSE | re.MULTILINE,
)

def recursive_add_to_index(dobj):
url = to_url_id(dobj.module)
if url != 0: # 0 is index.html
info = {
"ref": dobj.refname,
"url": url,
}
if index_docstrings:
info["doc"] = trim_docstring(dobj.docstring)
if isinstance(dobj, pdoc.Function):
info["func"] = 1

index.append(info)

for member_dobj in getattr(dobj, "doc", {}).values():
recursive_add_to_index(member_dobj)

@lru_cache()
def to_url_id(module):
url = module.url()
if top_module.is_package: # Reference from subfolder if its a package
_, url = url.split("/", maxsplit=1)
if url not in url_cache:
url_cache[url] = len(url_cache)
return url_cache[url]

index = []
url_cache = {}
recursive_add_to_index(top_module)
urls = [i[0] for i in sorted(url_cache.items(), key=lambda i: i[1])]

# If top module is a package, output the index in its subfolder, else, in the output dir
main_path = path.join(cli.args.output_dir, *top_module.name.split(".") if top_module.is_package else "")
with cli._open_write_file(path.join(main_path, "index.js")) as f:
f.write("URLS=")
json.dump(urls, f, indent=0, separators=(",", ":"))
f.write(";\nINDEX=")
json.dump(index, f, indent=0, separators=(",", ":"))

# Generate search.html
with cli._open_write_file(path.join(main_path, "search.html")) as f:
rendered_template = pdoc._render_template("/search.mako", module=top_module, **template_config)
f.write(rendered_template)

cli._generate_lunr_search = _patched_generate_lunr_search

cli.main()


Expand Down

0 comments on commit c8d88c8

Please sign in to comment.