def test_create_module_doc(self):
root = os.path.join(os.getcwd() + \
'/python-lib/cuddlefish/tests/static-files')
web_docs = webdocs.WebDocs(root)
module = web_docs.create_module_page(os.path.join(\
root + '/packages/aardvark/doc/aardvark-feeder.blah'))
self._test_common_contents(module)
self.assertTrue(\
'<title>aardvark-feeder - Add-on SDK Documentation</title>'\
in module)
self.assertTrue(\
'<h1>aardvark-feeder</h1>'\
in module)
self.assertTrue(\
'<div class="module_description">'\
in module)
self.assertTrue(\
'<p>The <code>aardvark-feeder</code> module simplifies feeding aardvarks.</p>'\
in module)
self.assertTrue(\
'<h2 class="api_header">API Reference</h2>'\
in module)
self.assertTrue(\
'<h3 class="api_header">Functions</h3>'\
in module)
self.assertTrue(\
'<h4 class="api_name">feed(food)</h4>'\
in module)
self.assertTrue(
'<p>Feed the aardvark.</p>'\
in module)
def generate_docs_from_scratch(env_root, base_url):
docs_dir = get_sdk_docs_path(env_root)
web_docs = webdocs.WebDocs(env_root, base_url)
must_rewrite_links = True
if base_url:
must_rewrite_links = False
clean_generated_docs(docs_dir)
# py2.5 doesn't have ignore=, so we delete tempfiles afterwards. If we
# required >=py2.6, we could use ignore=shutil.ignore_patterns("*~")
for (dirpath, dirnames, filenames) in os.walk(docs_dir):
for n in filenames:
if n.endswith("~"):
os.unlink(os.path.join(dirpath, n))
# generate api docs from all packages
os.mkdir(os.path.join(docs_dir, "packages"))
# create the index file and save that
pkg_cfg = packaging.build_pkg_cfg(env_root)
index = json.dumps(packaging.build_pkg_index(pkg_cfg))
index_path = os.path.join(docs_dir, "packages", 'index.json')
open(index_path, 'w').write(index)
# for each package, generate its docs
for pkg_name, pkg in pkg_cfg['packages'].items():
src_dir = pkg.root_dir
package_dirname = os.path.basename(src_dir)
dest_dir = os.path.join(docs_dir, "packages", package_dirname)
os.mkdir(dest_dir)
src_readme = os.path.join(src_dir, "README.md")
if os.path.exists(src_readme):
shutil.copyfile(src_readme, os.path.join(dest_dir, "README.md"))
# create the package page
package_filename = os.path.join(dest_dir, "index.html")
if not os.path.exists(package_filename):
package_doc_html = web_docs.create_package_page(pkg_name)
replace_file(env_root, package_filename, package_doc_html,
must_rewrite_links)
# generate all the API docs
docs_src_dir = os.path.join(src_dir, "doc")
if os.path.isdir(os.path.join(src_dir, "docs")):
docs_src_dir = os.path.join(src_dir, "docs")
generate_file_tree(env_root, docs_src_dir, web_docs, generate_api_doc,
must_rewrite_links)
# generate all the guide docs
dev_guide_src = os.path.join(docs_dir, "dev-guide-source")
generate_file_tree(env_root, dev_guide_src, web_docs, generate_guide_doc,
must_rewrite_links)
# make /md/dev-guide/welcome.html the top level index file
doc_html, dest_dir, filename = generate_guide_doc(
env_root, os.path.join(docs_dir, 'dev-guide-source', 'index.md'),
web_docs)
write_file(env_root, doc_html, docs_dir, 'index', False)
def test_create_guide2_doc(self):
root = os.path.join(os.getcwd() + \
'/python-lib/cuddlefish/tests/static-files')
web_docs = webdocs.WebDocs(root)
guide = web_docs.create_guide_page(os.path.join(\
root + '/doc/dev-guide-source/no_h1.blah'))
self._test_common_contents(guide)
self.assertTrue('<title>Add-on SDK Documentation</title>'\
in guide)
self.assertTrue('<h2>A heading</h2>'\
in guide)
def test_create_guide1_doc(self):
root = os.path.join(os.getcwd() + \
'/python-lib/cuddlefish/tests/static-files')
web_docs = webdocs.WebDocs(root)
guide = web_docs.create_guide_page(os.path.join(\
root + '/doc/dev-guide-source/welcome.blah'))
self._test_common_contents(guide)
self.assertTrue(\
'<title>An Imposing Title - Add-on SDK Documentation</title>'\
in guide)
self.assertTrue('<p><em>Some words!</em></p>'\
in guide)
def generate_named_file(env_root, base_url, filename):
docs_dir = os.path.join(env_root, DOCS_DIR)
web_docs = webdocs.WebDocs(env_root, base_url)
# next, generate api doc or guide doc
abs_path = os.path.abspath(filename)
if abs_path.startswith(os.path.join(env_root, 'packages')):
return generate_api_doc(env_root, abs_path, web_docs)
elif abs_path.startswith(
os.path.join(env_root, DOCS_DIR, 'dev-guide-source')):
return generate_guide_doc(env_root, abs_path, web_docs)
else:
raise ValueError("Not a valid path to a documentation file")
def generate_named_file(env_root, filename):
web_docs = webdocs.WebDocs(env_root, get_base_url(env_root))
# next, generate api doc or guide doc
abs_path = os.path.abspath(filename)
if abs_path.startswith(os.path.join(env_root, 'packages')):
doc_html, dest_dir, filename = generate_api_doc(
env_root, abs_path, web_docs)
write_file(env_root, doc_html, dest_dir, filename)
elif abs_path.startswith(
os.path.join(get_sdk_docs_path(env_root), 'dev-guide-source')):
doc_html, dest_dir, filename = generate_guide_doc(
env_root, abs_path, web_docs)
write_file(env_root, doc_html, dest_dir, filename, False)
else:
raise ValueError("Not a valid path to a documentation file")
def generate_named_file(env_root, filename_and_path):
module_list = get_module_list(env_root)
web_docs = webdocs.WebDocs(env_root, module_list, get_versions()["version"], get_base_url(env_root))
abs_path = os.path.abspath(filename_and_path)
path, filename = os.path.split(abs_path)
if abs_path.startswith(os.path.join(env_root, 'doc', 'module-source')):
module_root = os.sep.join([env_root, "doc", "module-source"])
module_info = ModuleInfo(env_root, module_root, path, filename)
write_module_doc(env_root, web_docs, module_info, False)
elif abs_path.startswith(os.path.join(get_sdk_docs_path(env_root), 'dev-guide-source')):
devguide_root = os.sep.join([env_root, "doc", "dev-guide-source"])
devguideitem_info = DevGuideItemInfo(env_root, devguide_root, path, filename)
write_devguide_doc(env_root, web_docs, devguideitem_info, False)
else:
raise ValueError("Not a valid path to a documentation file")
def test_create_package_doc(self):
root = os.path.join(os.getcwd() + \
'/python-lib/cuddlefish/tests/static-files')
web_docs = webdocs.WebDocs(root)
aarvark_package = web_docs.create_package_page('packages/aardvark')
self._test_common_contents(aarvark_package)
self.assertTrue('<h1>aardvark</h1>'\
in aarvark_package)
self.assertTrue(\
'<span class="meta-header">Author</span>'\
in aarvark_package)
self.assertTrue(\
'<span class="author">Jon Smith</span>'\
in aarvark_package)
self.assertTrue(\
'<title>aardvark - Add-on SDK Documentation</title>'\
in aarvark_package)
def test_create_guide1_doc(self):
root = os.path.join(os.getcwd() + \
'/python-lib/cuddlefish/tests/static-files')
self.copy_static_files(root)
module_list = get_module_list(root)
web_docs = webdocs.WebDocs(root, module_list)
guide = web_docs.create_guide_page(os.path.join(\
root + '/doc/dev-guide-source/index.md'))
self.rm_static_files(root)
self._test_common_contents(guide)
self.assertTrue(\
'<title>An Imposing Title - Add-on SDK Documentation</title>'\
in guide)
self.assertTrue('<p><em>Some words!</em></p>'\
in guide)
self.assertTrue('<div id="version">Version '\
in guide)
def test_create_module_doc(self):
root = os.path.join(os.getcwd() + \
'/python-lib/cuddlefish/tests/static-files')
self.copy_static_files(root)
module_list = get_module_list(root)
test_module_info = False
for module_info in module_list:
if module_info.name() == "aardvark-feeder":
test_module_info = module_info
break
self.assertTrue(test_module_info)
test_stability = test_module_info.metadata.get("stability", "undefined")
self.assertEqual(test_stability, "stable")
web_docs = webdocs.WebDocs(root, module_list)
module = web_docs.create_module_page(test_module_info)
self.rm_static_files(root)
self._test_common_contents(module)
self.assertTrue(\
'<title>aardvark-feeder - Add-on SDK Documentation</title>'\
in module)
self.assertTrue(\
'class="stability-note stability-stable"'\
in module)
self.assertTrue(\
'<h1>aardvark-feeder</h1>'\
in module)
self.assertTrue(\
'<div class="module_description">'\
in module)
self.assertTrue(\
'<p>The <code>aardvark-feeder</code> module simplifies feeding aardvarks.</p>'\
in module)
self.assertTrue(\
'<h2 class="api_header">API Reference</h2>'\
in module)
self.assertTrue(\
'<h3 class="api_header">Functions</h3>'\
in module)
self.assertTrue(\
'<h4 class="api_name">feed(food)</h4>'\
in module)
self.assertTrue(
'<p>Feed the aardvark.</p>'\
in module)
def generate_docs_from_scratch(env_root, version, base_url):
docs_dir = get_sdk_docs_path(env_root)
module_list = get_module_list(env_root)
web_docs = webdocs.WebDocs(env_root, module_list, version, base_url)
must_rewrite_links = True
if base_url:
must_rewrite_links = False
clean_generated_docs(docs_dir)
# py2.5 doesn't have ignore=, so we delete tempfiles afterwards. If we
# required >=py2.6, we could use ignore=shutil.ignore_patterns("*~")
for (dirpath, dirnames, filenames) in os.walk(docs_dir):
for n in filenames:
if n.endswith("~"):
os.unlink(os.path.join(dirpath, n))
# generate api docs for all modules
if not os.path.exists(os.path.join(docs_dir, "modules")):
os.mkdir(os.path.join(docs_dir, "modules"))
[write_module_doc(env_root, web_docs, module_info, must_rewrite_links) for module_info in module_list]
# generate third-party module index
third_party_index_file = os.sep.join([env_root, "doc", "module-source", "third-party-modules.md"])
third_party_module_list = [module_info for module_info in module_list if module_info.level() == "third-party"]
write_module_index(env_root, web_docs, third_party_index_file, third_party_module_list, must_rewrite_links)
# generate high-level module index
high_level_index_file = os.sep.join([env_root, "doc", "module-source", "high-level-modules.md"])
high_level_module_list = [module_info for module_info in module_list if module_info.level() == "high"]
write_module_index(env_root, web_docs, high_level_index_file, high_level_module_list, must_rewrite_links)
# generate low-level module index
low_level_index_file = os.sep.join([env_root, "doc", "module-source", "low-level-modules.md"])
low_level_module_list = [module_info for module_info in module_list if module_info.level() == "low"]
write_module_index(env_root, web_docs, low_level_index_file, low_level_module_list, must_rewrite_links)
# generate dev-guide docs
devguide_list = get_devguide_list(env_root)
[write_devguide_doc(env_root, web_docs, devguide_info, must_rewrite_links) for devguide_info in devguide_list]
# make /md/dev-guide/welcome.html the top level index file
doc_html = web_docs.create_guide_page(os.path.join(docs_dir, 'dev-guide-source', 'index.md'))
write_file(env_root, doc_html, docs_dir, 'index', False)
