def get_module_doc():
"""Gives the module documentation object."""
context = pdoc.Context()
module = pdoc.Module(pytest_notimplemented, context=context)
pdoc.link_inheritance(context=context)
return module
def test_to_html(self):
text = '''# Title
`pdoc.Module` is a `Doc`, not `dict`.
```
code block
```
reference: `package.foo`
'''
expected = '''<h1 id="title">Title</h1>
<p><a href="#pdoc.Module">Module</a> is a <a href="#pdoc.Doc">Doc</a>, not <code>dict</code>.</p>
<pre><code>code block
</code></pre>
<p>reference: <a href="/package.foo.ext">package.foo</a></p>'''
module = pdoc.Module(pdoc)
def link(dobj, *args, **kwargs):
return '<a href="{}">{}</a>'.format(dobj.url(relative_to=module),
dobj.qualname)
html = to_html(text, module=module, link=link)
self.assertEqual(html, expected)
self.assertIn('<a href=',
to_html('`pdoc.Doc.url()`', module=module, link=link))
self.assertIn('<code>foo.f()</code>',
to_html('`foo.f()`', module=module, link=link))
def test_Function_private_params(self):
func = pdoc.Function('f',
pdoc.Module(pdoc),
lambda a, _a, _b=None: None)
self.assertEqual(func.params(), ['a', '_a'])
func = pdoc.Function(
'f',
pdoc.Module(pdoc),
lambda _ok, a, _a, *args, _b=None, c=None, _d=None: None)
self.assertEqual(func.params(), ['_ok', 'a', '_a', '*args', 'c=None'])
func = pdoc.Function('f',
pdoc.Module(pdoc),
lambda a, b, *, _c=1: None)
self.assertEqual(func.params(), ['a', 'b'])
def test__all__(self):
module = pdoc.import_module(EXAMPLE_MODULE + '.index')
with patch.object(module, '__all__', ['B'], create=True):
mod = pdoc.Module(module)
with self.assertWarns(UserWarning): # Only B is used but __pdoc__ contains others
pdoc.link_inheritance()
self.assertEqual(list(mod.doc.keys()), ['B'])
def test_Class_docstring(self):
class A:
"""foo"""
class B:
def __init__(self):
"""foo"""
class C:
"""foo"""
def __init__(self):
"""bar"""
class D(C):
"""baz"""
class E(C):
def __init__(self):
"""baz"""
mod = pdoc.Module(pdoc)
self.assertEqual(pdoc.Class('A', mod, A).docstring, """foo""")
self.assertEqual(pdoc.Class('B', mod, B).docstring, """foo""")
self.assertEqual(pdoc.Class('C', mod, C).docstring, """foo\n\nbar""")
self.assertEqual(pdoc.Class('D', mod, D).docstring, """baz\n\nbar""")
self.assertEqual(pdoc.Class('E', mod, E).docstring, """foo\n\nbaz""")
def test_format_git_link(self):
url = format_git_link(
template='https://github.com/pdoc3/pdoc/blob/{commit}/{path}#L{start_line}-L{end_line}',
dobj=pdoc.Module(EXAMPLE_MODULE).find_ident('module.foo'),
)
self.assertRegex(url, r"https://github.com/pdoc3/pdoc/blob/[0-9a-f]{40}"
r"/pdoc/test/example_pkg/module.py#L\d+-L\d+")
def test_subclasses(self):
class A:
pass
class B(type):
pass
class C(A):
pass
class D(B):
pass
class G(C):
pass
class F(C):
pass
class E(C):
pass
mod = pdoc.Module(pdoc)
self.assertEqual(
[x.refname for x in pdoc.Class('A', mod, A).subclasses()],
[mod.find_class(C).refname])
self.assertEqual(
[x.refname for x in pdoc.Class('B', mod, B).subclasses()],
[mod.find_class(D).refname])
self.assertEqual(
[x.refname for x in pdoc.Class('C', mod, C).subclasses()],
[mod.find_class(x).refname for x in (E, F, G)])
def test_find_ident(self):
mod = pdoc.Module(EXAMPLE_MODULE)
self.assertIsInstance(mod.find_ident('subpkg'), pdoc.Module)
mod = pdoc.Module(pdoc)
self.assertIsInstance(mod.find_ident('subpkg'), pdoc.External)
self.assertIsInstance(mod.find_ident(EXAMPLE_MODULE + '.subpkg'), pdoc.Module)
nonexistent = 'foo()'
result = mod.find_ident(nonexistent)
self.assertIsInstance(result, pdoc.External)
self.assertEqual(result.name, nonexistent)
# Ref by class __init__
mod = pdoc.Module(pdoc)
self.assertIs(mod.find_ident('pdoc.Doc.__init__').obj, pdoc.Doc)
def get_module_doc():
"""Gives the module documentation object."""
context = pdoc.Context()
module = pdoc.Module(temptree, context=context)
pdoc.link_inheritance(context=context)
return module
def test_context(self):
context = {}
pdoc.Module(pdoc, context=context)
self.assertIn('pdoc', context)
self.assertIn('pdoc.cli', context)
self.assertIn('pdoc.cli.main', context)
self.assertIn('pdoc.Module', context)
self.assertIsInstance(context['pdoc'], pdoc.Module)
self.assertIsInstance(context['pdoc.cli'], pdoc.Module)
self.assertIsInstance(context['pdoc.cli.main'], pdoc.Function)
self.assertIsInstance(context['pdoc.Module'], pdoc.Class)
module = pdoc.Module(pdoc)
self.assertIsInstance(module.find_ident('pdoc.Module'), pdoc.Class)
pdoc.reset()
self.assertIsInstance(module.find_ident('pdoc.Module'), pdoc.External)
def docs(outdir="."):
"""Auto-generate documentation for wsp-tools in html.
**Parameters**
* **outdir** : _string_ <br />
The directory to write the output documentation. <br />
Default is "./".
"""
modules = ['wsp_tools']
context = pdoc.Context()
modules = [pdoc.Module(mod, context=context) for mod in modules]
pdoc.link_inheritance(context)
def recursive_htmls(mod):
yield mod.url(), mod.html()
for submod in mod.submodules():
yield from recursive_htmls(submod)
for mod in modules:
for module_url, html in recursive_htmls(mod):
output_url = Path(outdir).expanduser().joinpath(module_url)
if not Path(output_url).parent.exists():
Path(output_url).parent.mkdir(parents=True)
with open(output_url, "w+") as f:
f.write(html)
print("Documentation for wsp-tools written to: \n{}:".format(
Path(outdir).joinpath(modules[0].url())))
def generate_doc_types_json(modules, types_file_path):
doc_types_list = [{
'id': 'gcloud',
'contents': 'index.json',
'title': 'gcloud'
}]
for module_name in modules:
if module_name == 'gcloud.__init__':
continue
module_title = module_name.replace('.__init__', '').split('.')
module_contents = (module_name.replace('.', '/').replace(
'__init__', 'index'))
if len(module_name.split('.')) > 2:
module_id = module_name.replace('.', '/')
else:
module_id = (module_name.replace('.', '/'))
module_contents += '.json'
doc_type_object = build_type(module_id.replace('/__init__', ''),
module_title, module_contents)
doc_types_list.append(doc_type_object)
pdoc_module = pdoc.Module(pdoc.import_module(module_name),
allsubmodules=True)
for c in pdoc_module.classes():
generate_doc_types_classes_json(c, doc_types_list)
write_docs_file(types_file_path, json.dumps(doc_types_list))
def generate_docs(docs_dir: str):
"""
python callable that creates docs like docs/textwalker.html, docs/patternparser.py
Args:
docs_dir: location to output docs to
"""
if not os.path.exists(docs_dir):
print(f'{docs_dir} does not exist; creating dir')
os.mkdir(docs_dir)
mod_names = [
"textwalker", "textwalker.textwalker", "textwalker.pattern_parser",
"textwalker.utils"
]
context = pdoc.Context()
modules = [pdoc.Module(mod, context=context) for mod in mod_names]
pdoc.link_inheritance(context)
for module in modules:
if module.name == "textwalker":
filepath = os.path.join(docs_dir, 'index.html')
else:
pkg, modname = module.name.split('.')
filename = f'{modname}.html'
filepath = os.path.join(docs_dir, filename)
with open(filepath, 'w', encoding='utf-8') as fp:
fp.write(module.html())
print(f'wrote docs for module {module.name} to {filepath}')
def test_Function_params(self):
mod = pdoc.Module(pdoc)
func = pdoc.Function('f', mod, lambda a, _a, _b=None: None)
self.assertEqual(func.params(), ['a', '_a'])
func = pdoc.Function(
'f', mod, lambda _ok, a, _a, *args, _b=None, c=None, _d=None: None)
self.assertEqual(func.params(), ['_ok', 'a', '_a', '*args', 'c=None'])
func = pdoc.Function('f', mod, lambda a, b, *, _c=1: None)
self.assertEqual(func.params(), ['a', 'b'])
func = pdoc.Function('f', mod, lambda a, *, b, c: None)
self.assertEqual(func.params(), ['a', '*', 'b', 'c'])
func = pdoc.Function('f', mod, lambda a=os.environ, b=sys.stdout: None)
self.assertEqual(func.params(), ['a=os.environ', 'b=sys.stdout'])
class Foo(enum.Enum):
a, b = 1, 2
func = pdoc.Function('f', mod, lambda a=Foo.a: None)
self.assertEqual(func.params(), ['a=Foo.a'])
func = pdoc.Function('f', mod, lambda a=object(): None)
self.assertEqual(func.params(), ['a=<object object>'])
func = pdoc.Function('f', mod, lambda a=object(): None)
self.assertEqual(func.params(link=lambda x: ''),
['a=<object object>'])
# typed
def f(a: int, *b, c: typing.List[pdoc.Doc] = []):
pass
func = pdoc.Function('f', mod, f)
self.assertEqual(func.params(), ['a', '*b', "c=[]"])
self.assertEqual(func.params(annotate=True), [
'a:\N{NBSP}int', '*b',
"c:\N{NBSP}List[pdoc.Doc]\N{NBSP}=\N{NBSP}[]"
])
# typed, linked
def link(dobj):
return '<a href="{}">{}</a>'.format(dobj.url(relative_to=mod),
dobj.qualname)
self.assertEqual(func.params(annotate=True, link=link), [
'a:\N{NBSP}int', '*b',
"c:\N{NBSP}List[<a href=\"#pdoc.Doc\">Doc</a>]\N{NBSP}=\N{NBSP}[]"
])
def bug130_str_annotation(a: "str"):
return
self.assertEqual(
pdoc.Function('bug130', mod,
bug130_str_annotation).params(annotate=True),
['a:\N{NBSP}str'])
def test_Module_find_class(self):
class A:
__module__ = None
assert A.__module__ is None
mod = pdoc.Module(pdoc)
self.assertIsInstance(mod.find_class(pdoc.Doc), pdoc.Class)
self.assertIsInstance(mod.find_class(A), pdoc.External)
def export_doc():
pyinventory_module = pdoc.Module("pyinventory")
write_files(
pyinventory_module,
"../docs/website/static",
show_source_code=False,
show_type_annotations=True,
)
def get_package_modules(src: str = DEFAULT_PACKAGE_DIRECTORY) -> list:
# Public submodules are auto-imported
context = pdoc.Context()
modules = [pdoc.Module(mod, context=context) for mod in [
src,
]]
pdoc.link_inheritance(context)
return modules
def test_inherited_members(self):
mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
pdoc.link_inheritance()
a = mod.doc['A']
b = mod.doc['B']
self.assertEqual(b.inherited_members(), [(a, [a.doc['inherited'],
a.doc['overridden_same_docstring']])])
self.assertEqual(a.inherited_members(), [])
def test_Function_return_annotation(self):
import typing
def f() -> typing.List[typing.Union[str, pdoc.Doc]]:
pass
func = pdoc.Function('f', pdoc.Module(pdoc), f)
self.assertEqual(func.return_annotation(),
'List[Union[str,\N{NBSP}pdoc.Doc]]')
def export(email, password, useLocally, replaceLatestVersion, hasBreakingChange):
files = os.listdir("./dist")
whlFiles = [file for file in files if os.path.splitext(file)[1] == ".whl"]
assert len(whlFiles), "More than one whl files"
match = re.search("pyinventory-([.0-9]+)-py3-none-any.whl", whlFiles[0])
version = match.group(1)
res = "\n".join(open(GRAPHQL_PYINVENORY_PATH, "r").read().splitlines()[10:-1])
packages = json.loads(res)
client = InventoryClient(email, password, is_local_host=useLocally)
if len(packages) != 0:
latestVersion = packages[0]["version"]
if LooseVersion(version) == LooseVersion(latestVersion):
print("version {} is already exported".format(version))
if replaceLatestVersion:
print("Replace version {} with new version".format(version))
latestPackage = packages.pop(0)
try:
delete_file(client, latestPackage["whlFileKey"], True)
except Exception:
print(
f'whlFileKey {latestPackage["whlFileKey"]} cannot ' "be deleted"
)
else:
return
elif LooseVersion(version) < LooseVersion(latestVersion):
print(
"newer version {} is already exported than current version {}".format(
latestVersion, version
)
)
return
whlFileKey = store_file(
client, os.path.join("./dist", whlFiles[0]), "application/zip", True
)
newPackage = {
"version": version,
"whlFileKey": whlFileKey,
"uploadTime": datetime.isoformat(
datetime.fromtimestamp(int(time.time()))) + "+00:00",
"hasBreakingChange": hasBreakingChange
}
packages.insert(0, newPackage)
newContent = json.dumps(packages)
open(GRAPHQL_PYINVENORY_PATH, "w").write(
GRAPHQL_PYINVENORY_CONTENT.format(newContent)
)
pyinventory_module = pdoc.Module("pyinventory")
write_files(pyinventory_module, '../docs/website/static', show_source_code=False)
def test_class_variables_docstring_not_from_obj(self):
class C:
vars_dont = 0
but_clss_have_doc = int
with self.assertWarns(UserWarning):
doc = pdoc.Class('C', pdoc.Module('pdoc'), C)
self.assertEqual(doc.doc['vars_dont'].docstring, '')
self.assertIn('integer', doc.doc['but_clss_have_doc'].docstring)
def test_reST_include(self):
expected = '''<pre><code class="python"> x = 2
</code></pre>
<p>1
x = 2
x = 3
x =</p>'''
mod = pdoc.Module(pdoc.import_module(
os.path.join(TESTS_BASEDIR, EXAMPLE_MODULE, '_reST_include', 'test.py')))
text = inspect.getdoc(mod.obj)
html = to_html(text, module=mod)
self.assertEqual(html, expected)
# Ensure includes are resolved within docstrings already,
# e.g. for `pdoc.html_helpers.extract_toc()` to work
self.assertIn('Command-line interface',
pdoc.Module(pdoc).docstring)
def test_namespace(self):
# Test the three namespace types
# https://packaging.python.org/guides/packaging-namespace-packages/#creating-a-namespace-package
for i in range(1, 4):
path = os.path.join(TESTS_BASEDIR, EXAMPLE_MODULE, '_namespace', str(i))
with patch.object(sys, 'path', [os.path.join(path, 'a'),
os.path.join(path, 'b')]):
mod = pdoc.Module('a.main')
self.assertIn('D', mod.doc)
def test_Class_params(self):
class C:
def __init__(self, x):
pass
mod = pdoc.Module(pdoc)
self.assertEqual(pdoc.Class('C', mod, C).params(), ['x'])
with patch.dict(mod.obj.__pdoc__, {'C.__init__': False}):
self.assertEqual(pdoc.Class('C', mod, C).params(), [])
def export_doc():
warnings.simplefilter("error", category=ReferenceWarning)
pyinventory_module = pdoc.Module("pyinventory")
write_files(
pyinventory_module,
"../docs/website/static",
show_source_code=False,
show_type_annotations=True,
)
def test_to_html_refname_warning(self):
mod = pdoc.Module(EXAMPLE_MODULE)
def f():
"""Reference to some `example_pkg.nonexisting` object"""
mod.doc['__f'] = pdoc.Function('__f', mod, f)
with self.assertWarns(ReferenceWarning) as cm:
mod.html()
del mod.doc['__f']
self.assertIn('example_pkg.nonexisting', cm.warning.args[0])
def test__pdoc__dict(self):
module = pdoc.import_module(EXAMPLE_MODULE)
with patch.object(module, '__pdoc__', {'B': False}):
mod = pdoc.Module(module)
pdoc.link_inheritance()
self.assertIn('A', mod.doc)
self.assertNotIn('B', mod.doc)
with patch.object(module, '__pdoc__', {'B.f': False}):
mod = pdoc.Module(module)
pdoc.link_inheritance()
self.assertIn('B', mod.doc)
self.assertNotIn('f', mod.doc['B'].doc)
self.assertIsInstance(mod.find_ident('B.f'), pdoc.External)
# GH-125: https://github.com/pdoc3/pdoc/issues/125
with patch.object(module, '__pdoc__', {'B.inherited': False}):
mod = pdoc.Module(module)
pdoc.link_inheritance()
self.assertNotIn('inherited', mod.doc['B'].doc)
def main():
for m in documented_sdk_modules:
html = pdoc.html(m, allsubmodules=True)
with open(module_to_docpath(m), 'w') as f:
f.write(html)
import mycroft
mycroft.__all__ = [m[8:] for m in documented_sdk_modules]
root_module = pdoc.Module(mycroft)
html = root_module.html(external_links=False, link_prefix='', source=True)
with open(module_to_docpath("mycroft"), 'w') as f:
f.write(html)
def test_Variable_type_annotation(self):
import typing
class Foobar:
@property
def prop(self) -> typing.Optional[int]:
pass
cls = pdoc.Class('Foobar', pdoc.Module(pdoc), Foobar)
prop = cls.instance_variables()[0]
self.assertEqual(prop.type_annotation(), 'Union[int,\N{NBSP}NoneType]')
def test_link_inheritance(self):
mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
with warnings.catch_warnings(record=True) as w:
pdoc.link_inheritance()
pdoc.link_inheritance()
self.assertFalse(w)
mod._is_inheritance_linked = False
with self.assertWarns(UserWarning):
pdoc.link_inheritance()
# Test inheritance across modules
pdoc.reset()
mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE + '._test_linking'))
pdoc.link_inheritance()
a = mod.doc['a'].doc['A']
b = mod.doc['b'].doc['B']
c = mod.doc['b'].doc['c'].doc['C']
self.assertEqual(b.inherits, a)
self.assertEqual(b.doc['a'].inherits, a.doc['a'])
self.assertEqual(b.doc['c'].inherits, c.doc['c'])
