def make(self, format: str) -> str:
pdoc.render.configure(**self.render_options)
pdoc.render.env.globals["__version__"] = "$VERSION"
if self.with_output_directory:
with tempfile.TemporaryDirectory() as tmpdirname:
tmpdir = Path(tmpdirname)
# noinspection PyTypeChecker
pdoc.pdoc(self.path,
format=format,
output_directory=Path(tmpdir)) # type: ignore
rendered = '<style type="text/css">iframe {width: 100%; min-height: 50vh}</style>\n'
for f in sorted(tmpdir.glob("**/*"), reverse=True):
if not f.is_file():
continue
rendered += (
f'<h3>{f.relative_to(tmpdir).as_posix()}</h3>\n' +
'<iframe srcdoc="\n' +
f.read_text("utf8").replace("&", "&").replace(
""" " """.strip(), """) + '\n"></iframe>\n\n')
else:
# noinspection PyTypeChecker
rendered = pdoc.pdoc(self.path, format=format) # type: ignore
pdoc.render.configure()
pdoc.render.env.globals["__version__"] = pdoc.__version__
return rendered
def test_smoke(module):
try:
with pdoc.extract.mock_some_common_side_effects():
importlib.import_module(module)
except pdoc.extract.AnyException:
pass
else:
# noinspection PyTypeChecker
pdoc.pdoc(module, format="repr")
pdoc.pdoc(module, format="html")
def test_api(tmp_path):
assert pdoc(here / "testdata" /
"demo_long.py").startswith("<!doctype html>")
with pytest.raises(ValueError, match="Invalid rendering format"):
assert pdoc(here / "testdata" / "demo_long.py", format="invalid")
with pytest.raises(ValueError, match="Module not found"):
with pytest.warns(RuntimeWarning, match="Cannot find spec"):
assert pdoc(here / "notfound.py", )
# temporarily insert syntax error - we don't leave it permanently to not confuse mypy, flake8 and black.
(here / "syntax_err" / "syntax_err.py").write_bytes(b"class")
with pytest.warns(RuntimeWarning,
match="Error importing test.syntax_err.syntax_err"):
pdoc(here / "syntax_err", output_directory=tmp_path)
(here / "syntax_err" / "syntax_err.py"
).write_bytes(b"# syntax error will be inserted by test here\n")
def cli(args: list[str] = None) -> None:
""" Command-line entry point """
opts = parser.parse_args(args)
if opts.version:
print(
f"pdoc: {get_dev_version()}\n"
f"Python: {platform.python_version()}\n"
f"Platform: {platform.platform()}"
)
return
render.configure(
edit_url_map=dict(x.split("=", 1) for x in opts.edit_url),
template_directory=opts.template_directory,
docformat=opts.docformat,
)
if opts.output_directory:
pdoc.pdoc(
*opts.modules,
output_directory=opts.output_directory,
format="html", # opts.format or
)
return
else:
all_modules: Collection[str]
if opts.modules:
all_modules = extract.parse_specs(opts.modules)
else:
all_modules = pdoc.web.AllModules()
with pdoc.web.DocServer(
(opts.host, opts.port),
all_modules,
) as httpd:
url = f"http://{opts.host}:{opts.port}"
print(f"pdoc server ready at {url}")
if not opts.no_browser:
if len(opts.modules) == 1:
mod = next(iter(all_modules))
url += f"/{mod.replace('.', '/')}.html"
pdoc.web.open_browser(url)
try:
httpd.serve_forever()
except KeyboardInterrupt:
httpd.server_close()
return
def make(self, format: str) -> str:
render.configure(**self.render_options)
paths = [self.path]
if self.extra:
paths.append(self.extra)
# noinspection PyTypeChecker
rendered = pdoc.pdoc(*paths, format=format) # type: ignore
render.configure()
return rendered
def generate(projroot: str) -> None:
"""Main entry point."""
from batools.version import get_current_version
import pdoc
# Since we're operating on source dirs, suppress .pyc generation.
# (__pycache__ dirs in source dirs causes some subtle headaches in
# the private repo)
sys.dont_write_bytecode = True
# Make sure we're running from the dir above this script.
os.chdir(projroot)
templatesdir = (Path(projroot) / 'assets' / 'src' / 'pdoc' /
'templates').absolute()
pythondir = (Path(projroot) / 'assets' / 'src' / 'ba_data' /
'python').absolute()
outdirname = (Path(projroot) / 'build' / 'docs_html').absolute()
sys.path.append(str(pythondir))
version, build_number = get_current_version()
try:
os.environ['BA_DOCS_GENERATION'] = '1'
pdoc.render.env.globals['ba_version'] = version
pdoc.render.env.globals['ba_build'] = build_number
pdoc.render.configure(search=True,
show_source=True,
template_directory=templatesdir)
pdoc.pdoc('ba', 'bastd', output_directory=outdirname)
except Exception as exc:
import traceback
traceback.print_exc()
raise CleanError('Docs generation failed') from exc
print(f'{Clr.GRN}Docs generation complete.{Clr.RST}')
#!/usr/bin/env python3
from pathlib import Path
from pdoc import pdoc, render
import os
here = Path(__file__).parent
with open(here / "index.py", "w") as index_py:
print("'''", file=index_py)
with open(here / "INDEX.md", "r") as index_md:
index = index_md.read()
print(index.replace("docs/", "./"), file=index_py)
print("'''", file=index_py)
render.configure(docformat="numpy", template_directory=here / "pdoc-template")
pdoc("run", "index", output_directory=here / "docs")
os.remove(here / "index.py")