Update of documentation configuration

Author: HaHeho

doc/conf.py

@@ -11,62 +11,69 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import os
+import sys
+
 # 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('../'))
+sys.path.insert(0, os.path.abspath("../"))
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
+needs_sphinx = "1.4"
 
 # 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.todo',
-    'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.githubpages',
-    'sphinx.ext.napoleon'
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.coverage",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
 ]
 
 # 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 encoding of source files.
 #
 # source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = 'Sound Field Analysis toolbox for Python'
-copyright = '2016, Christoph Hohnerlein (QU Lab)'
-author = 'Christoph Hohnerlein (QU Lab)'
+project = "Sound Field Analysis toolbox for Python"
+author = (
+    "Christoph Hohnerlein (QU Labs) \\and "
+    "Jens Ahrens (Chalmers) \\and "
+    "Hannes Helmholz (Chalmers)"
+)
+# noinspection PyShadowingBuiltins
+copyright = "2020, Chalmers University of Technology"
 
 # 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.3'
+version = (
+    open("../sound_field_analysis/_version.py").readlines()[-1].split()[-1].strip("\"'")
+)
 # The full version, including alpha/beta/rc tags.
-release = '0.3'
+release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -87,66 +94,83 @@
 # 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 reST default role (used for this markup: `text`) to use for all
 # documents.
 #
 # default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
-#
-# add_function_parentheses = True
+add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-#
-# add_module_names = True
+add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
 #
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # A list of ignored prefixes for module index sorting.
-# modindex_common_prefix = []
+modindex_common_prefix = ["sound_field_analysis."]
 
 # If true, keep warnings as "system message" paragraphs in the built documents.
+#
 # keep_warnings = False
 
+# A list of warning types to suppress arbitrary warning messages.
+#
+# suppress_warnings = ["image.not_readable"]
+
+# This value selects if automatically documented members are sorted alphabetical
+# (value 'alphabetical'), by member type (value 'groupwise') or by source order
+# (value 'bysource'). The default is alphabetical.
+autodoc_member_order = "bysource"
+
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
 # --  Napoleon settings ----------------------------------------------
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
 napoleon_include_private_with_doc = False
 napoleon_include_special_with_doc = True
-napoleon_use_admonition_for_examples = False
-napoleon_use_admonition_for_notes = False
-napoleon_use_admonition_for_references = False
+napoleon_use_admonition_for_examples = True
+napoleon_use_admonition_for_notes = True
+napoleon_use_admonition_for_references = True
 napoleon_use_ivar = False
-napoleon_use_param = True
-napoleon_use_rtype = True
+napoleon_use_param = False
+napoleon_use_rtype = False
 
 # -- 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 = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # 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 = {  # Toc options
+    "display_version": True,
+    "collapse_navigation": False,
+    "sticky_navigation": True,
+    "navigation_depth": -1,
+    "includehidden": True,
+    "titles_only": False,
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ["_themes", ]
+html_theme_path = [
+    "_themes",
+]
 
 # The name for this set of Sphinx documents.
 # "<project> v<release> documentation" by default.
@@ -171,7 +195,8 @@
 # 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"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -236,8 +261,7 @@
 # Sphinx supports the following languages:
 #   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
 #   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh'
-#
-# html_search_language = 'en'
+html_search_language = "en"
 
 # A dictionary with options for the search language support, empty by default.
 # 'ja' uses this config value.
@@ -256,34 +280,35 @@
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
-     # The paper size ('letterpaper' or 'a4paper').
-     'papersize': 'a4paper',
-
-     # Remove blank pages
-     'classoptions': ',openany,oneside',
-     'babel': '\\usepackage[english]{babel}',
-
-     # The font size ('10pt', '11pt' or '12pt').
-     #
-     # 'pointsize': '10pt',
-
-     # Additional stuff for the LaTeX preamble.
-     #
-     # 'preamble': '',
-
-     # Latex figure (float) alignment
-     #
-     # 'figure_align': 'htbp',
+    # The paper size ('letterpaper' or 'a4paper').
+    "papersize": "a4paper",
+    # Remove blank pages
+    "classoptions": ",openany,oneside",
+    "babel": "\\usepackage[english]{babel}",
+    # The font size ('10pt', '11pt' or '12pt').
+    "pointsize": "10pt",
+    # Additional stuff for the LaTeX preamble.
+    # 'preamble': '',
+    # Latex figure (float) alignment
+    # 'figure_align': 'htbp',
 }
 
 # 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, 'sfa_readme.tex', 'Sound Field Analysis Toolbox Readme',
-     'Christoph Hohnerlein (QU Lab)', 'manual', True),
+    (
+        master_doc,
+        htmlhelp_basename + ".tex",
+        "Sound Field Analysis toolbox Documentation",
+        author,
+        "manual",
+        True,
+    ),
 ]
 
+# supported_image_types = ['application/pdf', 'image/png', 'image/jpeg']
+
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 #
@@ -322,8 +347,13 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'sfa_readme', 'Sound Field Analysis Toolbox Readme',
-     [author], 1)
+    (
+        master_doc,
+        htmlhelp_basename,
+        "Sound Field Analysis toolbox Documentation",
+        [author],
+        1,
+    )
 ]
 
 # If true, show URL addresses after external links.
@@ -337,9 +367,15 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'sfa_readme', 'Sound Field Analysis Toolbox for Python Readme',
-     author, 'sfa_readme', 'Analyze, visualize and process sound field data recorded by spherical microphone arrays.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        htmlhelp_basename,
+        "Sound Field Analysis toolbox Documentation",
+        author,
+        htmlhelp_basename,
+        "Analyze, visualize and process sound field data recorded by spherical microphone arrays.",
+        "Miscellaneous",
+    ),
 ]
 
 # Documents to append as an appendix to all manuals.

doc/generators.rst

@@ -1,20 +1,18 @@
-Welcome to the Sound Field Analysis toolbox for Python!
-=======================================================
-
-Contents:
+Sound Field Analysis toolbox Documentation
+==========================================
 
 .. toctree::
    :maxdepth: 2
+   :caption: Contents:
 
    usage
-   generators
-   processing
-   plotting
+   modules
    reference
 
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
+* :ref:`modindex`
 * :ref:`search`

doc/index.rst

@@ -0,0 +1,37 @@
+Modules
+=======
+
+Generators
+----------
+.. automodule:: sound_field_analysis.gen
+    :noindex:
+
+I/O
+---
+.. automodule:: sound_field_analysis.io
+    :noindex:
+
+Lebedev
+-------
+.. automodule:: sound_field_analysis.lebedev
+    :noindex:
+
+Plotting
+--------
+.. automodule:: sound_field_analysis.plot
+    :noindex:
+
+Processing
+----------
+.. automodule:: sound_field_analysis.process
+    :noindex:
+
+Spherical
+---------
+.. automodule:: sound_field_analysis.sph
+    :noindex:
+
+Utilities
+---------
+.. automodule:: sound_field_analysis.utils
+    :noindex: