def __init__(self, package_name, dst="_source", ignore=[]): if "." in package_name: raise Exception("package_name has to be a root package.") self.package_name = package_name self.package = Package(package_name) self.dst = dst self.ignore = [i.replace(".py", "") for i in ignore]
class ApiReferenceDoc(object): """A class used to generate sphinx-doc api reference part. :param package_name: the importable package name :type package_name: string :param dst: default "_source", the directory you want to put doc files :type dst: string :param ignore: default empty list, package, module prefix you want to ignored :type ignore: list of string **中文文档** 如果你需要忽略一个包: 请使用 ``docfly.packages`` 如果你需要忽略一个模块: 请使用 ``docfly.zzz_manual_install`` 或 ``docfly.zzz_manual_install.py`` """ def __init__(self, package_name, dst="_source", ignore=[]): if "." in package_name: raise Exception("package_name has to be a root package.") self.package_name = package_name self.package = Package(package_name) self.dst = dst self.ignore = [i.replace(".py", "") for i in ignore] def fly(self): """Generate doc tree. """ dst = self.dst # create an temp alias try: os.mkdir(dst) except: pass # delete everything already exists package_dir = os.path.join(os.path.abspath(dst), self.package_name) try: shutil.rmtree(package_dir) except Exception as e: print("'%s' can't be removed! Error: %s" % (package_dir, e)) # create .rst files for pkg, parent, fullname, sub_packages, sub_modules in self.package.walk(): if not self.isignored(pkg): dir_path = os.path.join(*( [dst, ] + fullname.split(".") )) init_path = os.path.join(dir_path, "__init__.rst") self.make_dir(dir_path) self.make_file(init_path, self.generate_package_content(pkg)) for mod in sub_modules: if not self.isignored(mod): module_path = os.path.join(dir_path, mod.name + ".rst") self.make_file( module_path, self.generate_module_content(mod)) def isignored(self, mod_or_pkg): """Find whether if we need include a :class:`docfly.packages.member.Package` or :class:`docfly.packages.member.Module`. **中文文档** 根据全名判断一个包或者模块是否需要被ignore. """ for pattern in self.ignore: if mod_or_pkg.fullname.startswith(pattern): return True return False def make_dir(self, abspath): """Make an empty directory. """ try: os.mkdir(abspath) print("Made: %s" % abspath) except: pass def make_file(self, abspath, text): """Make a file with utf-8 text. """ try: with open(abspath, "wb") as f: f.write(text.encode("utf-8")) print("Made: %s" % abspath) except: pass def generate_package_content(self, package): """Generate package.rst text content. :: {{ package_name }} ================== .. automodule:: {{ package_name }} :members: sub packages and modules ------------------------ .. toctree:: :maxdepth: 1 {{ sub_package_name1 }} <{{ sub_package_name1 }}/__init__> {{ sub_package_name2 }} <{{ sub_package_name2 }}/__init__> {{ sub_module_name1}} <{{ sub_module_name1}}> {{ sub_module_name2}} <{{ sub_module_name2}}> """ if isinstance(package, Package): return jinja2.Template(tc.package).render(package=package, isignored=self.isignored) else: raise Exception("%r is not a Package object" % package) def generate_module_content(self, module): """Generate module.rst text content. :: {{ module_name }} ================= .. automodule:: {{ module_fullname }} :members: """ if isinstance(module, Module): return jinja2.Template(tc.module).render(module=module) else: raise Exception("%r is not a Module object" % module)