Merge pull request #69 from vanderhe/recipeThemingAndExtensions

Change recipe theming and add copy-button extension

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,54 +208,57 @@
 # 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()
     archivedir = os.path.join(cwd, ARCHIVE_DIR)
     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):

doc/recipes/requirements.txt

@@ -1,3 +1,5 @@
 sphinx >= 1.8
 sphinxcontrib-bibtex
-sphinx-rtd-theme
+sphinx-book-theme
+sphinx-copybutton
+sphinx-design