def make_docsrc(project_dir, verbose: bool = True): """Make source folder for documentation based on setup.cfg metadata :param project_dir: Path to root project directory containing setup.cfg """ # copy _static/docsrc files to project_dir/docsrc if verbose: print('Making and populating a docsrc directory (for documentation)') docsrc_src = _STATIC_FILES / 'docsrc' if not docsrc_src.is_dir(): raise RuntimeError(f'Epythet module missing files in: {docsrc_src}') docsrc_dst = Path(project_dir).absolute() / 'docsrc' if sys.version_info.minor >= 8: shutil.copytree(str(docsrc_src), str(docsrc_dst), dirs_exist_ok=True) else: shutil.copytree(str(docsrc_src), str(docsrc_dst)) docsrc_static_dir = docsrc_dst / '_static' docsrc_static_dir.mkdir(parents=True, exist_ok=True) # make master file project, copyright, author, release, display_name = parse_config( Path(project_dir) / 'setup.cfg' ) title = master_file_title_t.format(display_name=display_name) make_master_file(docsrc_dir=docsrc_dst, title=title)
def make_autodocs( project_dir: Union[str, Path], output_dirname='module_docs', skip_existing=True, docsrc_dir=None, ignore: List[str] = None, ): """Create sphinx autodocs and table of contents for module defined by setup.cfg :param project_dir: Path to root project directory containing setup.cfg :param output_dirname: directory name to be created under docsrc :param skip_existing: existing docs will not be overwritten if True :param docsrc_dir: path to sphinx docs source file :param ignore: skip file if path contains any ignore strings """ project_dir = Path(project_dir).absolute() project_name, _, _, _, _ = parse_config(project_dir / 'setup.cfg') if docsrc_dir is None: docsrc_dir = project_dir / 'docsrc' module_dir = project_dir / project_name make_autodocs_for_modules_files( module_dir=module_dir, docsrc_dir=docsrc_dir, output_dirname=output_dirname, skip_existing=skip_existing, ignore=ignore, )
# -- Path setup -------------------------------------------------------------- # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. import os import sys sys.path.insert(0, os.path.abspath('..')) # -- Project information ----------------------------------------------------- from epythet.config_parser import parse_config from pathlib import Path project, copyright, author, release, display_name = parse_config( Path(__file__).absolute().parent.parent / 'setup.cfg') # -- General configuration --------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ 'sphinx_toggleprompt', 'sphinx_copybutton', 'sphinx.ext.autodoc', # Include documentation from docstrings 'sphinx.ext.doctest', # Test snippets in the documentation 'sphinx.ext.githubpages', # This extension creates .nojekyll file 'sphinx.ext.graphviz', # Add Graphviz graphs 'sphinx.ext.napoleon', # Support for NumPy and Google style docstrings 'sphinx.ext.todo', # Support for todo items