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)