diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 000000000..cbf825f0c --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,8 @@ + +html[data-theme="light"] { + --pst-color-primary: #18609d; /* pyfar blue as primary color */ +} + +html[data-theme="dark"] { + --pst-color-primary: #18609d; /* pyfar blue as primary color */ +} diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 000000000..0c96ea3a0 Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/_templates/navbar-nav.html b/docs/_templates/navbar-nav.html new file mode 100644 index 000000000..afcdd67b7 --- /dev/null +++ b/docs/_templates/navbar-nav.html @@ -0,0 +1,41 @@ +
+
diff --git a/docs/conf.py b/docs/conf.py index 6b14aa146..918eaa3d4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,37 +1,20 @@ -#!/usr/bin/env python -# -*- coding: utf-8 -*- +# Configuration file for the Sphinx documentation builder. # -# pyfar documentation build configuration file, created by -# sphinx-quickstart on Fri Jun 9 13:47:02 2017. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -# 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('..')) import pyfar # noqa -# -- General configuration --------------------------------------------- +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# 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.autodoc', 'sphinx.ext.viewcode', @@ -40,7 +23,10 @@ 'matplotlib.sphinxext.plot_directive', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx', - 'autodocsumm'] + 'autodocsumm', + 'sphinx_design', + 'sphinx_favicon', +] # show tocs for classes and functions of modules using the autodocsumm # package @@ -51,21 +37,19 @@ plot_include_source = True # 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' # The master toctree document. master_doc = 'index' # General information about the project. -project = u'pyfar' -copyright = u"2020-2022, The pyfar developers" -author = u"The pyfar developers" +project = 'pyfar' +copyright = '2020, The pyfar developers' +author = 'The pyfar developers' # The version info for the project you're documenting, acts as replacement # for |version| and |release|, also used in various other places throughout @@ -76,9 +60,6 @@ # The full version, including alpha/beta/rc tags. release = pyfar.__version__ -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. language = 'en' @@ -109,86 +90,40 @@ 'spharpy': ('https://spharpy.readthedocs.io/en/stable/', None) } -# -- Options for HTML output ------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'insipid' - -# 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 = {} - -# 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'] - - -# -- Options for HTMLHelp output --------------------------------------- - -# Output file base name for HTML help builder. -htmlhelp_basename = 'pyfardoc' - - -# -- Options for LaTeX output ------------------------------------------ - -latex_elements = { - # 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', +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'pydata_sphinx_theme' +html_static_path = ['_static'] +html_css_files = ['css/custom.css'] +html_logo = 'resources/logos/pyfar_logos_fixed_size_pyfar.png' +html_title = "pyfar" +html_favicon = '_static/favicon.ico' + +# -- HTML theme options +# https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html + +html_theme_options = { + "navbar_start": ["navbar-logo"], + "navbar_end": ["navbar-icon-links", "theme-switcher"], + "navbar_align": "content", + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/pyfar", + "icon": "fa-brands fa-square-github", + "type": "fontawesome", + }, + ], + # Configure secondary (right) side bar + "show_toc_level": 3, # Show all subsections of notebooks + "secondary_sidebar_items": ["page-toc"], # Omit 'show source' link that that shows notebook in json format + "navigation_with_keys": True, } -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass -# [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'pyfar.tex', - u'pyfar Documentation', - u'Marco Berzborn', 'manual'), -] - - -# -- Options for manual page output ------------------------------------ - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'pyfar', - u'pyfar Documentation', - [author], 1) -] - - -# -- Options for Texinfo output ---------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'pyfar', - u'pyfar Documentation', - author, - 'pyfar', - 'One line description of project.', - 'Miscellaneous'), -] - +html_context = { + "default_mode": "light" +} # -- pyfar specifics ----------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 186698df5..23af1c176 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,9 +2,6 @@ :width: 150 :alt: Alternative text -|pyfar_logo| - - Getting Started =============== @@ -35,7 +32,7 @@ Contributing =============== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 contributing diff --git a/docs/resources/logos/pyfar_logos_fixed_size_pyfar.png b/docs/resources/logos/pyfar_logos_fixed_size_pyfar.png new file mode 100644 index 000000000..b21ec8775 Binary files /dev/null and b/docs/resources/logos/pyfar_logos_fixed_size_pyfar.png differ diff --git a/requirements_dev.txt b/requirements_dev.txt index 6dba83f34..a7a832fe2 100644 --- a/requirements_dev.txt +++ b/requirements_dev.txt @@ -14,8 +14,10 @@ scipy>=1.5.0 matplotlib<=3.7 urllib3 deepdiff -insipid-sphinx-theme autodocsumm soundfile>=0.11.0 sofar>=1.1.1 nbmake>=0.7.0 +pydata-sphinx-theme +sphinx-design +sphinx-favicon