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