diff --git a/doc/recipes/docs/conf.py b/doc/recipes/docs/conf.py index be58958..d38989b 100644 --- a/doc/recipes/docs/conf.py +++ b/doc/recipes/docs/conf.py @@ -24,54 +24,50 @@ # -- Project information ----------------------------------------------------- -project = 'Fortnet' -copyright = '2020 - 2022, T. W. van der Heide' -author = 'T. W. van der Heide' - -# The full version, including alpha/beta/rc tags -release = '0.7' - +project = "Fortnet Recipes" +copyright = "2022, T. W. van der Heide" +author = "T. W. van der Heide" # -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. # -needs_sphinx = '1.8' +needs_sphinx = "1.8" # 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.ext.mathjax', 'sphinxcontrib.bibtex'] -bibtex_bibfiles = ['refs.bib'] -bibtex_encoding = 'utf-8-sig' -bibtex_default_style = 'unsrt' -bibtex_reference_style = 'label' +extensions = [ + "sphinx.ext.mathjax", + "sphinx_copybutton", + "sphinx_design", + "sphinxcontrib.bibtex", +] +bibtex_bibfiles = ["refs.bib"] +bibtex_encoding = "utf-8-sig" +bibtex_default_style = "unsrt" +bibtex_reference_style = "label" # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = ".rst" # The master toctree document. -master_doc = 'index' - -# General information about the project. -project = 'Fortnet Recipes' -copyright = '2022, T. W. van der Heide' -author = 'T. W. van der Heide' +master_doc = "index" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '0.7' +version = "0.7" # The full version, including alpha/beta/rc tags. -release = '0.7' +release = "0.7" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -83,10 +79,10 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = "sphinx" # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False @@ -95,10 +91,10 @@ numfig = True numfig_format = { - 'figure': 'Figure %s', - 'table': 'Table %s', - 'code-block': 'Listing %s', - 'section': 'Section' + "figure": "Figure %s", + "table": "Table %s", + "code-block": "Listing %s", + "section": "Section", } @@ -107,29 +103,33 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_rtd_theme' -html_logo = '../../../utils/art/logo_doc.svg' -html_theme_options = { - 'logo_only': False, - 'display_version': True, -} - +html_theme = "sphinx_book_theme" +html_title = project +html_logo = "../../../utils/art/logo.svg" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # -#html_theme_options = {} +html_theme_options = { + "logo_only": False, + "repository_url": "https://github.com/vanderhe/fortnet", + "repository_branch": "master", + "use_repository_button": True, + "use_edit_page_button": True, + "use_download_button": False, + "path_to_docs": "doc/recipes/docs", +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -#html_static_path = ['_static'] +# html_static_path = ['_static'] # -- Options for HTMLHelp output ------------------------------------------ # Output file base name for HTML help builder. -htmlhelp_basename = 'FortnetRecipesdoc' +htmlhelp_basename = "FortnetRecipesdoc" # -- Options for LaTeX output --------------------------------------------- @@ -138,15 +138,12 @@ # The paper size ('letterpaper' or 'a4paper'). # # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). # # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. # # 'preamble': '', - # Latex figure (float) alignment # # 'figure_align': 'htbp', @@ -156,8 +153,13 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'FortnetRecipes.tex', 'Fortnet Recipes Documentation', - 'T. W. van der Heide', 'manual'), + ( + master_doc, + "FortnetRecipes.tex", + "Fortnet Recipes", + "T. W. van der Heide", + "manual", + ), ] @@ -166,8 +168,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'fortnetrecipes', 'Fortnet Recipes Documentation', - [author], 1) + (master_doc, "fortnetrecipes", "Fortnet Recipes", [author], 1) ] @@ -177,13 +178,18 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'FortnetRecipes', 'Fortnet Recipes Documentation', - author, 'FortnetRecipes', 'One line description of project.', - 'Miscellaneous'), + ( + master_doc, + "FortnetRecipes", + "Fortnet Recipes", + author, + "FortnetRecipes", + "One line description of project.", + "Miscellaneous", + ), ] - # -- Options for Epub output ---------------------------------------------- # Bibliographic Dublin Core info. @@ -202,26 +208,27 @@ # epub_uid = '' # A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] +epub_exclude_files = ["search.html"] # -- Additional functionality to archive files in _downloads + def setup(app): - app.connect('builder-inited', create_archives) + app.connect("builder-inited", create_archives) def create_archives(app): - '''Creates a .tar.bz2 archive in _downloads for each entry in _archives.''' + """Creates a .tar.bz2 archive in _downloads for each entry in _archives.""" import os import tarfile from sphinx.util import logging - ARCHIVE_DIR = '_archives' - DOWNLOAD_DIR = '_downloads/archives' - IGNORE_FILE = '_ignore' - COMPRESSION = 'bz2' + ARCHIVE_DIR = "_archives" + DOWNLOAD_DIR = "_downloads/archives" + IGNORE_FILE = "_ignore" + COMPRESSION = "bz2" logger = logging.getLogger(__name__) cwd = os.getcwd() @@ -229,27 +236,29 @@ def create_archives(app): downloaddir = os.path.join(cwd, DOWNLOAD_DIR) if not os.path.exists(downloaddir): os.makedirs(downloaddir) - archives = [fname for fname in os.listdir(archivedir) if fname[0] != '_'] + archives = [fname for fname in os.listdir(archivedir) if fname[0] != "_"] tarfilter = _get_tar_filter(os.path.join(archivedir, IGNORE_FILE)) for archive in archives: - tarname = os.path.join(DOWNLOAD_DIR, archive + '.tar.' + COMPRESSION) + tarname = os.path.join(DOWNLOAD_DIR, archive + ".tar." + COMPRESSION) tarpath = os.path.join(cwd, tarname) filename = os.path.join(ARCHIVE_DIR, archive) filepath = os.path.join(cwd, filename) tartime = os.path.getmtime(tarpath) if os.path.exists(tarpath) else 0.0 filetime = _newest_modification_time(filepath) if tartime <= filetime: - with tarfile.open(tarpath, 'w:' + COMPRESSION) as tar: + with tarfile.open(tarpath, "w:" + COMPRESSION) as tar: tar.add(filepath, arcname=archive, filter=tarfilter) - logger.info('Created archive {} from {}'.format(tarname, filename)) + logger.info("Created archive {} from {}".format(tarname, filename)) else: - logger.info('Skipped unchanged archive {} from {}'\ - .format(tarname, filename)) + logger.info( + "Skipped unchanged archive {} from {}".format(tarname, filename) + ) def _newest_modification_time(filepath): - '''Returns the newest modification time among all files within a folder.''' + """Returns the newest modification time among all files within a folder.""" import os + mtime = os.lstat(filepath).st_mtime for root, dirs, entries in os.walk(filepath): for entry in dirs + entries: @@ -259,14 +268,14 @@ def _newest_modification_time(filepath): def _get_tar_filter(ignorefile): - '''Filters out all files matching any pattern in an ignore file''' + """Filters out all files matching any pattern in an ignore file""" import os import fnmatch if not os.path.exists(ignorefile): return None - - with open(ignorefile, 'r') as fobj: + + with open(ignorefile, "r") as fobj: patterns = [line.strip() for line in fobj.readlines()] def tar_filter(tarinfo): diff --git a/doc/recipes/requirements.txt b/doc/recipes/requirements.txt index 114addc..6c2ad71 100644 --- a/doc/recipes/requirements.txt +++ b/doc/recipes/requirements.txt @@ -1,3 +1,5 @@ sphinx >= 1.8 sphinxcontrib-bibtex -sphinx-rtd-theme +sphinx-book-theme +sphinx-copybutton +sphinx-design