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 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 generate_doc_types_json(modules, types_file_path):
doc_types_list = [{
'id': 'google-cloud',
'contents': 'index.json',
'title': 'google-cloud'
}]
for module_name in modules:
if module_name == 'google.cloud.__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 do_GET(self):
# Deny favicon shortcut early.
if self.path == "/favicon.ico":
return None
importlib.invalidate_caches()
code = 200
if self.path == "/":
modules = [pdoc.import_module(module, reload=True)
for module in self.args.modules]
modules = sorted((module.__name__, inspect.getdoc(module))
for module in modules)
out = pdoc._render_template('/html.mako',
modules=modules,
**self.template_config)
elif self.path.endswith(".ext"):
# External links are a bit weird. You should view them as a giant
# hack. Basically, the idea is to "guess" where something lives
# when documenting another module and hope that guess can actually
# track something down in a more global context.
#
# The idea here is to start specific by looking for HTML that
# exists that matches the full external path given. Then trim off
# one component at the end and try again.
#
# If no HTML is found, then we ask `pdoc` to do its thang on the
# parent module in the external path. If all goes well, that
# module will then be able to find the external identifier.
import_path = self.path[:-4].lstrip("/")
resolved = self.resolve_ext(import_path)
if resolved is None: # Try to generate the HTML...
print("Generating HTML for %s on the fly..." % import_path, file=sys.stderr)
try:
out = pdoc.html(import_path.split(".")[0], **self.template_config)
except Exception as e:
print('Error generating docs: {}'.format(e), file=sys.stderr)
# All hope is lost.
code = 404
out = "External identifier <code>%s</code> not found." % import_path
else:
return self.redirect(resolved)
# Redirect '/pdoc' to '/pdoc/' so that relative links work
# (results in '/pdoc/cli.html' instead of 'cli.html')
elif not self.path.endswith(('/', '.html')):
return self.redirect(self.path + '/')
# Redirect '/pdoc/index.html' to '/pdoc/' so it's more pretty
elif self.path.endswith(pdoc._URL_PACKAGE_SUFFIX):
return self.redirect(self.path[:-len(pdoc._URL_PACKAGE_SUFFIX)] + '/')
else:
try:
out = self.html()
except ImportError:
code = 404
out = "Module <code>%s</code> not found." % self.import_path_from_req_url
self.send_response(code)
self.send_header("Content-type", "text/html; charset=utf-8")
self.end_headers()
self.echo(out)
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_to_html_refname_warning(self):
mod = pdoc.Module(pdoc.import_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_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.import_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(pdoc.import_module('a.main'))
self.assertIn('D', mod.doc)
def test_find_ident(self):
mod = pdoc.Module(pdoc.import_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)
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'])
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)
def test_module(self):
modules = {
EXAMPLE_MODULE: ('', ('index', 'module', 'subpkg', 'subpkg2')),
os.path.join(EXAMPLE_MODULE, 'subpkg2'): ('.subpkg2', ('subpkg2.module',)),
}
with chdir(TESTS_BASEDIR):
for module, (name_suffix, submodules) in modules.items():
with self.subTest(module=module):
m = pdoc.Module(pdoc.import_module(module))
self.assertEqual(repr(m), "<Module '{}'>".format(m.obj.__name__))
self.assertEqual(m.name, EXAMPLE_MODULE + name_suffix)
self.assertEqual(sorted(m.name for m in m.submodules()),
[EXAMPLE_MODULE + '.' + m for m in submodules])
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.__init__': False}):
mod = pdoc.Module(module)
pdoc.link_inheritance()
self.assertIn('B', mod.doc)
self.assertNotIn('__init__', mod.doc['B'].doc)
self.assertIsInstance(mod.find_ident('B.__init__'), pdoc.External)
def check_modified(self):
try:
module = pdoc.import_module(self.import_path_from_req_url)
new_etag = str(os.stat(module.__file__).st_mtime)
except ImportError:
return 404
old_etag = self.headers.get('If-None-Match', new_etag)
if old_etag == new_etag:
# Don't log repeating checks
self.log_request = lambda *args, **kwargs: None
return 304
return 205
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.doc['a'].inherits, a.doc['a'])
self.assertEqual(b.doc['c'].inherits, c.doc['c'])
# While classes do inherit from superclasses, they just shouldn't always
# say so, because public classes do want to be exposed and linked to
self.assertNotEqual(b.inherits, a)
def test_readonly_value_descriptors(self):
pdoc.reset()
mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
var = mod.doc['B'].doc['ro_value_descriptor']
self.assertIsInstance(var, pdoc.Variable)
self.assertTrue(var.instance_var)
self.assertEqual(var.docstring, """ro_value_descriptor docstring""")
self.assertTrue(var.source)
var = mod.doc['B'].doc['ro_value_descriptor_no_doc']
self.assertIsInstance(var, pdoc.Variable)
self.assertTrue(var.instance_var)
self.assertEqual(var.docstring, """Read-only value descriptor""")
self.assertTrue(var.source)
def test_url(self):
mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
pdoc.link_inheritance()
c = mod.doc['D']
self.assertEqual(c.url(), 'example_pkg/index.html#example_pkg.D')
self.assertEqual(c.url(link_prefix='/'), '/example_pkg/index.html#example_pkg.D')
self.assertEqual(c.url(relative_to=c.module), '#example_pkg.D')
self.assertEqual(c.url(top_ancestor=True), 'example_pkg/index.html#example_pkg.B')
f = c.doc['overridden']
self.assertEqual(f.url(), 'example_pkg/index.html#example_pkg.D.overridden')
self.assertEqual(f.url(link_prefix='/'), '/example_pkg/index.html#example_pkg.D.overridden')
self.assertEqual(f.url(relative_to=c.module), '#example_pkg.D.overridden')
self.assertEqual(f.url(top_ancestor=1), 'example_pkg/index.html#example_pkg.B.overridden')
def test_inherits(self):
module = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
pdoc.link_inheritance()
a = module.doc['A']
b = module.doc['B']
self.assertEqual(b.doc['inherited'].inherits, a.doc['inherited'])
self.assertEqual(b.doc['overridden_same_docstring'].inherits,
a.doc['overridden_same_docstring'])
self.assertEqual(b.doc['overridden'].inherits, None)
c = module.doc['C']
d = module.doc['D']
self.assertEqual(d.doc['overridden'].inherits, c.doc['overridden'])
self.assertEqual(c.doc['overridden'].inherits, b.doc['overridden'])
def test_qualname(self):
module = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
var = module.doc['var']
cls = module.doc['B']
nested_cls = cls.doc['C']
cls_var = cls.doc['var']
method = cls.doc['f']
self.assertEqual(pdoc.External('foo').qualname, 'foo')
self.assertEqual(module.qualname, EXAMPLE_MODULE)
self.assertEqual(var.qualname, 'var')
self.assertEqual(cls.qualname, 'B')
self.assertEqual(nested_cls.qualname, 'B.C')
self.assertEqual(cls_var.qualname, 'B.var')
self.assertEqual(method.qualname, 'B.f')
def documentation():
choice = [(project.id, project.project_name)
for project in Project.query.filter_by(
company_id=current_user.company_id)]
form = UploadForm()
form.projects.choices = choice
if request.method == 'POST':
if form.validate_on_submit():
name = form.file.data.filename
project_id = form.projects.data
if not allowed_file(name):
return render_template('error.html',
message='Is this file python script?')
form.file.data.save(os.path.join(os.path.abspath(''), 'review.py'))
libpath = os.path.abspath('templates')
project = Project.query.filter_by(id=project_id).first()
try:
mod = pdoc.import_module('review')
doc = pdoc.Module(mod)
html = doc.html()
except Exception as e:
print(e)
return render_template(
'error.html',
user=current_user.user_username,
message='Something wrong in your module!')
else:
now = datetime.now()
filename = str(uuid.uuid4())
with open(os.path.join(libpath, f"{filename}.html"), "w") as f:
f.write(html)
file = File(user_username=current_user.user_username,
project_id=project.id,
file_name=name,
upload_time=str(now),
documentation=filename)
db.session.add(file)
db.session.commit()
return html
return render_template('error.html',
message='Not valid form!',
user=current_user.user_username)
return render_template('documentation.html',
user=current_user.user_username,
form=form)
def from_module_name(cls, name, base_path):
module = pdoc.Module(pdoc.import_module(name), allsubmodules=True)
methods = module.functions() + module.variables()
examples = []
if '__init__' in name:
snippets = get_snippet_examples(
name.split('.')[1], os.path.join(base_path, 'docs'))
examples.extend(snippets)
source_path = clean_source_path(module)
return cls(module_id=name,
name=name.split('.')[-1].title(),
description=module.docstring,
examples=examples or [],
methods=[Method.from_pdoc(m) for m in methods],
source=source_path)
def from_module_name(cls, name, base_path):
module = pdoc.Module(pdoc.import_module(name), allsubmodules=True)
methods = module.functions() + module.variables()
examples = []
if '__init__' in name:
snippets = get_snippet_examples(name.split('.')[1],
os.path.join(base_path, 'docs'))
examples.extend(snippets)
source_path = clean_source_path(module)
return cls(module_id=name,
name=name.split('.')[-1].title(),
description=module.docstring,
examples=examples or [],
methods=[Method.from_pdoc(m) for m in methods],
source=source_path)
def generate_module_docs(modules, docs_path, real_base_path, toc):
for module_name in modules:
module = Module.from_module_name(module_name, real_base_path)
pdoc_module = pdoc.Module(pdoc.import_module(module_name),
allsubmodules=True)
for c in pdoc_module.classes():
generate_class_docs(pdoc_module, c, docs_path, toc)
module_path = (module_name.replace('.',
'/').replace('__init__', 'index'))
module_docs_path = os.path.join(docs_path, module_path) + '.json'
if pdoc_module.functions():
toc_key = module_name.replace('gcloud.', '').split('.')[0]
toc_entry = build_toc_entry(module.name, module_path)
toc['services'][toc_key].append(toc_entry)
write_docs_file(module_docs_path,
json.dumps(module.to_dict(), indent=2, sort_keys=True))
def test_refname(self):
mod = EXAMPLE_MODULE + '.' + 'subpkg'
module = pdoc.Module(pdoc.import_module(mod))
var = module.doc['var']
cls = module.doc['B']
nested_cls = cls.doc['C']
cls_var = cls.doc['var']
method = cls.doc['f']
self.assertEqual(pdoc.External('foo').refname, 'foo')
self.assertEqual(module.refname, mod)
self.assertEqual(var.refname, mod + '.var')
self.assertEqual(cls.refname, mod + '.B')
self.assertEqual(nested_cls.refname, mod + '.B.C')
self.assertEqual(cls_var.refname, mod + '.B.var')
self.assertEqual(method.refname, mod + '.B.f')
# Inherited method's refname points to class' implicit copy
pdoc.link_inheritance()
self.assertEqual(cls.doc['inherited'].refname, mod + '.B.inherited')
def generate_module_docs(modules, docs_path, real_base_path, toc):
for module_name in modules:
module = Module.from_module_name(module_name, real_base_path)
pdoc_module = pdoc.Module(pdoc.import_module(module_name),
allsubmodules=True)
for c in pdoc_module.classes():
generate_class_docs(pdoc_module, c, docs_path, toc)
module_path = (module_name.replace('.', '/')
.replace('__init__', 'index'))
module_docs_path = os.path.join(docs_path, module_path) + '.json'
if pdoc_module.functions():
toc_key = module_name.replace('google.cloud.', '').split('.')[0]
toc_entry = build_toc_entry(module.name, module_path)
toc['services'][toc_key].append(toc_entry)
write_docs_file(module_docs_path,
json.dumps(module.to_dict(),
indent=2, sort_keys=True))
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 documentation():
if session.get('username'):
form = UploadForm()
if request.method == 'POST':
if form.validate_on_submit():
name = form.file.data.filename
if allowed_file(name):
form.file.data.save(os.path.join(os.path.abspath(''), 'review.py'))
libpath = os.path.abspath('templates')
try:
mod = pdoc.import_module('review')
doc = pdoc.Module(mod)
html = doc.html()
except Exception as e:
print(e)
return render_template('error.html',
user=session.get('username'),
message='Something wrong in your module!')
else:
now = datetime.now()
user = User.query.filter_by(user_email=session.get('username')).first()
file = File(user_id=user.id,
file_name=name,
language_id=1,
upload_time=str(now))
db.session.add(file)
filename = str(uuid.uuid4())
file = File.query.filter_by(user_id=user.id, file_name=name, upload_time=str(now)).first()
doc = Documentation(documentation_name=filename, file_id=file.id)
db.session.add(doc)
db.session.commit()
with open(os.path.join(libpath, f"{filename}.html"), "w") as f:
f.write(html)
return html
return render_template('error.html', user=session.get('username'), message='Not valid file format!')
return render_template('error.html', message='Not valid form!', user=session.get('username'))
return render_template('documentation.html', user=session.get('username'), form=form)
return render_template('notlogin.html', user=None)
def test_sorting(self):
module = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
sorted_variables = module.variables()
unsorted_variables = module.variables(sort=False)
self.assertNotEqual(sorted_variables, unsorted_variables)
self.assertEqual(sorted_variables, sorted(unsorted_variables))
sorted_functions = module.functions()
unsorted_functions = module.functions(sort=False)
self.assertNotEqual(sorted_functions, unsorted_functions)
self.assertEqual(sorted_functions, sorted(unsorted_functions))
sorted_classes = module.classes()
unsorted_classes = module.classes(sort=False)
self.assertNotEqual(sorted_classes, unsorted_classes)
self.assertEqual(sorted_classes, sorted(unsorted_classes))
cls = module.doc["Docformats"]
sorted_methods = cls.methods()
unsorted_methods = cls.methods(sort=False)
self.assertNotEqual(sorted_methods, unsorted_methods)
self.assertEqual(sorted_methods, sorted(unsorted_methods))
def main():
if args.version:
print(pdoc.__version__)
sys.exit(0)
# We close stdin because some modules, upon import, are not very polite
# and block on stdin.
try:
sys.stdin.close()
except:
pass
if not args.http and args.module_name is None:
_eprint('No module name specified.')
sys.exit(1)
if args.template_dir is not None:
pdoc.tpl_lookup.directories.insert(0, args.template_dir)
if args.http:
args.html = True
args.external_links = True
args.html_dir = args.http_dir
args.overwrite = True
args.link_prefix = '/'
# If PYTHONPATH is set, let it override everything if we want it to.
pypath = os.getenv('PYTHONPATH')
if args.only_pypath and pypath is not None and len(pypath) > 0:
pdoc.import_path = pypath.split(path.pathsep)
if args.http:
if args.module_name is not None:
_eprint('Module names cannot be given with --http set.')
sys.exit(1)
# Run the HTTP server.
httpd = HTTPServer((args.http_host, args.http_port), WebDoc)
print('pdoc server ready at http://%s:%d'
% (args.http_host, args.http_port), file=sys.stderr)
httpd.serve_forever()
httpd.server_close()
sys.exit(0)
docfilter = None
if args.ident_name and len(args.ident_name.strip()) > 0:
search = args.ident_name.strip()
def docfilter(o):
rname = o.refname
if rname.find(search) > -1 or search.find(o.name) > -1:
return True
if isinstance(o, pdoc.Class):
return search in o.doc or search in o.doc_init
return False
# Try to do a real import first. I think it's better to prefer
# import paths over files. If a file is really necessary, then
# specify the absolute path, which is guaranteed not to be a
# Python import path.
try:
module = pdoc.import_module(args.module_name)
except Exception as e:
module = None
# Get the module that we're documenting. Accommodate for import paths,
# files and directories.
if module is None:
isdir = path.isdir(args.module_name)
isfile = path.isfile(args.module_name)
if isdir or isfile:
fp = path.realpath(args.module_name)
module_name = path.basename(fp)
if isdir:
fp = path.join(fp, '__init__.py')
else:
module_name, _ = path.splitext(module_name)
# Use a special module name to avoid import conflicts.
# It is hidden from view via the `Module` class.
with open(fp) as f:
module = imp.load_source('__pdoc_file_module__', fp, f)
if isdir:
module.__path__ = [path.realpath(args.module_name)]
module.__pdoc_module_name = module_name
else:
module = pdoc.import_module(args.module_name)
module = pdoc.Module(module, docfilter=docfilter,
allsubmodules=args.all_submodules)
# Plain text?
if not args.html:
output = module.text()
try:
print(output)
except IOError as e:
# This seems to happen for long documentation.
# This is obviously a hack. What's the real cause? Dunno.
if e.errno == 32:
pass
else:
raise e
sys.exit(0)
# HTML output depends on whether the module being documented is a package
# or not. If not, then output is written to {MODULE_NAME}.html in
# `html-dir`. If it is a package, then a directory called {MODULE_NAME}
# is created, and output is written to {MODULE_NAME}/index.html.
# Submodules are written to {MODULE_NAME}/{MODULE_NAME}.m.html and
# subpackages are written to {MODULE_NAME}/{MODULE_NAME}/index.html. And
# so on... The same rules apply for `http_dir` when `pdoc` is run as an
# HTTP server.
if not args.http:
quit_if_exists(module)
html_out(module)
sys.exit(0)
search = args.ident_name.strip()
def docfilter(o):
rname = o.refname
if rname.find(search) > -1 or search.find(o.name) > -1:
return True
if isinstance(o, pdoc.Class):
return search in o.doc or search in o.doc_init
return False
# Try to do a real import first. I think it's better to prefer
# import paths over files. If a file is really necessary, then
# specify the absolute path, which is guaranteed not to be a
# Python import path.
try:
module = pdoc.import_module(args.module_name)
except Exception as e:
module = None
# Get the module that we're documenting. Accommodate for import paths,
# files and directories.
if module is None:
isdir = path.isdir(args.module_name)
isfile = path.isfile(args.module_name)
if isdir or isfile:
fp = path.realpath(args.module_name)
module_name = path.basename(fp)
if isdir:
fp = path.join(fp, '__init__.py')
else:
module_name, _ = path.splitext(module_name)
def test_imported_once(self):
with chdir(os.path.join(TESTS_BASEDIR, EXAMPLE_MODULE)):
pdoc.import_module('_imported_once.py')
def test_import_filename(self):
with patch.object(sys, 'path', ['']), \
chdir(os.path.join(TESTS_BASEDIR, EXAMPLE_MODULE)):
pdoc.import_module('index')
class Docformats(unittest.TestCase):
_module = pdoc.Module(pdoc)
_docmodule = pdoc.import_module(EXAMPLE_MODULE)
@staticmethod
def _link(dobj, *args, **kwargs):
return '<a>`{}`</a>'.format(dobj.refname)
def test_numpy(self):
expected = '''<p>Summary line.</p>
<h2 id="parameters">Parameters</h2>
<dl>
<dt><strong><code>x1</code></strong>, <strong><code>x2</code></strong> : <code>array_like</code></dt>
<dd>
<p>Input arrays,
description of <code>x1</code>, <code>x2</code>.</p>
<div class="admonition versionadded">
<p class="admonition-title">Added in version: 1.5.0</p>
</div>
</dd>
<dt><strong><code>x</code></strong> : { <code>NoneType</code>, <code>'B'</code>, <code>'C'</code> }, optional</dt>
<dd> </dd>
<dt><strong><code>n</code></strong> : <code>int</code> or <code>list</code> of <code>int</code></dt>
<dd>Description of num</dd>
<dt><strong><code>*args</code></strong>, <strong><code>**kwargs</code></strong></dt>
<dd>Passed on.</dd>
</dl>
<h2 id="returns">Returns</h2>
<dl>
<dt><strong><code>output</code></strong> : <a><code>pdoc.Doc</code></a></dt>
<dd>The output array</dd>
</dl>
<h2 id="raises">Raises</h2>
<dl>
<dt><strong><code>TypeError</code></strong></dt>
<dd>When something.</dd>
</dl>
<h2 id="see-also">See Also</h2>
<p><code>fromstring</code>, <code>loadtxt</code></p>
<h2 id="see-also_1">See Also</h2>
<dl>
<dt><a><code>pdoc.text</code></a></dt>
<dd>Function a with its description.</dd>
<dt><a><code>scipy.random.norm</code></a></dt>
<dd>Random variates, PDFs, etc.</dd>
</dl>
<h2 id="notes">Notes</h2>
<p>Foo bar.</p>
<h3 id="h3-title">H3 Title</h3>
<p>Foo bar.</p>''' # noqa: E501
text = inspect.getdoc(self._docmodule.numpy)
html = to_html(text, module=self._module, link=self._link)
self.assertEqual(html, expected)
def test_google(self):
expected = '''<p>Summary line.
Nomatch:</p>
<h2 id="args">Args</h2>
<dl>
<dt><strong><code>arg1</code></strong> : <code>int</code></dt>
<dd>Description of arg1</dd>
<dt><strong><code>arg2</code></strong> : <code>str</code> or <code>int</code></dt>
<dd>Description of arg2</dd>
<dt><strong><code>*args</code></strong></dt>
<dd>passed around</dd>
</dl>
<h2 id="returns">Returns</h2>
<dl>
<dt><strong><code>bool</code></strong></dt>
<dd>Description of return value</dd>
</dl>
<h2 id="raises">Raises</h2>
<dl>
<dt><strong><code>AttributeError</code></strong></dt>
<dd>
<p>The <code>Raises</code> section is a list of all exceptions
that are relevant to the interface.</p>
<p>and a third line.</p>
</dd>
<dt><strong><code>ValueError</code></strong></dt>
<dd>If <code>arg2</code> is equal to <code>arg1</code>.</dd>
</dl>
<h2 id="examples">Examples</h2>
<p>Examples in doctest format.</p>
<pre><code>>>> a = [1,2,3]
</code></pre>
<h2 id="todos">Todos</h2>
<ul>
<li>For module TODOs</li>
</ul>'''
text = inspect.getdoc(self._docmodule.google)
html = to_html(text, module=self._module, link=self._link)
self.assertEqual(html, expected)
def test_doctests(self):
expected = '''<p>Need an intro paragrapgh.</p>
<pre><code>>>> Then code is indented one level
</code></pre>
<p>Alternatively</p>
<pre><code>fenced code works
</code></pre>'''
text = inspect.getdoc(self._docmodule.doctests)
html = to_html(text, module=self._module, link=self._link)
self.assertEqual(html, expected)
def test_reST_directives(self):
expected = '''<div class="admonition todo">
<p class="admonition-title">TODO</p>
<p>Create something.</p>
</div>
<div class="admonition admonition">
<p class="admonition-title">Example</p>
<p>Image shows something.</p>
<p><img alt="" src="/logo.png"></p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Can only nest admonitions two levels.</p>
</div>
</div>
<p><img alt="" src="https://www.debian.org/logos/openlogo-nd-100.png"></p>
<p>Now you know.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Some warning
lines.</p>
</div>
<ul>
<li>
<p>Describe some func in a list
across multiple lines:</p>
<div class="admonition deprecated">
<p class="admonition-title">Deprecated since version: 3.1</p>
<p>Use <code>spam</code> instead.</p>
</div>
<div class="admonition versionadded">
<p class="admonition-title">Added in version: 2.5</p>
<p>The <em>spam</em> parameter.</p>
</div>
</li>
</ul>
<div class="admonition caution">
<p class="admonition-title">Caution</p>
<p>Don't touch this!</p>
</div>'''
text = inspect.getdoc(self._docmodule.reST_directives)
html = to_html(text, module=self._module, link=self._link)
self.assertEqual(html, expected)
def test__pdoc__invalid_value(self):
module = pdoc.import_module(EXAMPLE_MODULE)
with patch.object(module, '__pdoc__', {'B': 1}), \
self.assertRaises(ValueError):
pdoc.Module(module)
pdoc.link_inheritance()
def setUpClass(cls):
cls._module = pdoc.Module(pdoc)
cls._docmodule = pdoc.import_module(EXAMPLE_MODULE)
used = {}
for subdir, dirs, files in os.walk('.'):
for file in files:
if file.endswith('.py'):
program = file.split('.py')[0]
if program in used: continue
used[program] = 1
progress = [0,0]
for program in used.keys():
print("Documenting",program+"...")
try:
mod = pdoc.Module(pdoc.import_module(program))
doc = open("docs/"+program+".html",'w')
writ = mod.html()
doc.write(writ)
doc.close()
print("Documented",program)
progress[0] += 1
except (ImportError, SyntaxError,AttributeError) as e:
print("Failed to document",program,e)
progress[1] += 1
print("Documented",progress[0],'files')
print("Failed on",progress[1],'files')
