use gallery style and update doc

.gitignore

@@ -107,3 +107,10 @@ ENV/
 
 # OS stuff
 .DS_Store
+
+# ignore downloads from pyfar gallery
+docs/header.rst
+docs/_static/favicon.ico
+docs/_static/header.rst
+docs/_static/css/custom.css
+docs/resources/logos/pyfar_logos_fixed_size_imkar.png

HISTORY.rst

@@ -2,7 +2,7 @@
 History
 =======
 
-0.1.0 (2022-09-19)
+0.1.0 (2024-03-28)
 ------------------
 
 * First release on PyPI.

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022, The pyfar developers
+Copyright (c) 2024, The pyfar developers
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

MANIFEST.in

@@ -1,4 +1,3 @@
-include AUTHORS.rst
 include CONTRIBUTING.rst
 include HISTORY.rst
 include LICENSE

README.rst

@@ -3,24 +3,28 @@ imkar
 =====
 
 
-.. image:: https://img.shields.io/pypi/v/imkar.svg
-        :target: https://pypi.python.org/pypi/imkar
+.. image:: https://badge.fury.io/py/imkar.svg
+    :target: https://badge.fury.io/py/imkar
+.. image:: https://readthedocs.org/projects/imkar/badge/?version=latest
+    :target: https://imkar.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+.. image:: https://circleci.com/gh/pyfar/imkar.svg?style=shield
+    :target: https://circleci.com/gh/pyfar/imkar
 
-.. image:: https://img.shields.io/cirrus/github/pyfar/imkar.svg
-        :target: https://app.circleci.com/pipelines/github/pyfar/imkar
 
-.. image:: https://readthedocs.org/projects/imkar/badge/?version=latest
-        :target: https://imkar.readthedocs.io/en/latest/?version=latest
-        :alt: Documentation Status
 
 
 A python package for material modeling and quantification in acoustics.
 
+
+* Free software: MIT license
+
+
 Getting Started
 ===============
 
 Check out `read the docs`_ for the complete documentation. Packages
-related to imkar are listed at `pyfar.org`_.
+related to pyfar are listed at `pyfar.org`_.
 
 Installation
 ============
@@ -39,6 +43,6 @@ Contributing
 Refer to the `contribution guidelines`_ for more information.
 
 
-.. _contribution guidelines: https://github.com/pyfar/imkar/blob/main/CONTRIBUTING.rst
+.. _contribution guidelines: https://github.com/pyfar/imkar/blob/develop/CONTRIBUTING.rst
 .. _pyfar.org: https://pyfar.org
 .. _read the docs: https://imkar.readthedocs.io/en/latest

docs/conf.py

@@ -1,44 +1,35 @@
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
+# Configuration file for the Sphinx documentation builder.
 #
-# imkar 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
+import urllib3
+import shutil
 sys.path.insert(0, os.path.abspath('..'))
 
 import imkar  # 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',
     'sphinx.ext.napoleon',
     'sphinx.ext.autosummary',
+    'matplotlib.sphinxext.plot_directive',
     'sphinx.ext.mathjax',
-    'autodocsumm']
+    'sphinx.ext.intersphinx',
+    'autodocsumm',
+    'sphinx_design',
+    'sphinx_favicon',
+    'sphinx_reredirects',
+]
 
 # show tocs for classes and functions of modules using the autodocsumm
 # package
@@ -49,20 +40,18 @@
 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 = 'imkar'
-copyright = "2022, The pyfar developers"
+copyright = "2024, The pyfar developers"
 author = "The pyfar developers"
 
 # The version info for the project you're documenting, acts as replacement
@@ -74,9 +63,6 @@
 # The full version, including alpha/beta/rc tags.
 release = imkar.__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'
@@ -99,82 +85,74 @@
 # default language for highlighting in source code
 highlight_language = "python3"
 
-# -- 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 = 'pydata_sphinx_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 = {}
-
-# 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']
-
+# intersphinx mapping
+intersphinx_mapping = {
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/', None),
+    'matplotlib': ('https://matplotlib.org/stable/', None),
+    'pyfar': ('https://pyfar.readthedocs.io/en/stable/', None),
+    }
 
-# -- Options for HTMLHelp output ---------------------------------------
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'imkardoc'
-
-
-# -- 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',
+html_theme = 'pydata_sphinx_theme'
+html_static_path = ['_static']
+html_css_files = ['css/custom.css']
+html_logo = 'resources/logos/pyfar_logos_fixed_size_imkar.png'
+html_title = "imkar"
+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",
+    "header_links_before_dropdown": 8,
+    "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, 'imkar.tex',
-     'imkar Documentation',
-     'The pyfar developers', '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, 'imkar',
-     'imkar Documentation',
-     [author], 1)
-]
-
+html_context = {
+   "default_mode": "light"
+}
 
-# -- Options for Texinfo output ----------------------------------------
+# redirect index to pyfar.html
+redirects = {
+     "index": "imkar.html"
+}
 
-# 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, 'imkar',
-     'imkar Documentation',
-     author,
-     'imkar',
-     'One line description of project.',
-     'Miscellaneous'),
-]
+# -- download navbar and style files from gallery -----------------------------
+branch = 'add-imkar'
+link = f'https://github.com/pyfar/gallery/raw/{branch}/docs/'
+folders_in = [
+    '_static/css/custom.css',
+    '_static/favicon.ico',
+    '_static/header.rst',
+    'resources/logos/pyfar_logos_fixed_size_imkar.png',
+    ]
+c = urllib3.PoolManager()
+for file in folders_in:
+    url = link + file
+    filename = file
+    os.makedirs(os.path.dirname(filename), exist_ok=True)
+    with c.request('GET', url, preload_content=False) as res, open(filename, 'wb') as out_file:
+        shutil.copyfileobj(res, out_file)
+
+# replace pyfar hard link to internal link
+with open("_static/header.rst", "rt") as fin:
+    with open("header.rst", "wt") as fout:
+        for line in fin:
+            fout.write(line.replace(f'https://{project}.readthedocs.io', project))

docs/imkar.rst

@@ -0,0 +1,29 @@
+imkar
+=====
+
+.. toctree::
+   :caption: Getting Started
+   :maxdepth: 2
+
+   readme
+
+
+.. toctree::
+   :caption: Documentation
+   :maxdepth: 2
+
+   modules
+
+
+.. toctree::
+   :caption: Contributing
+   :maxdepth: 1
+
+   contributing
+
+
+.. toctree::
+   :caption: Other
+   :maxdepth: 1
+
+   history

docs/index.rst

@@ -1,38 +1,2 @@
-Getting Started
-===============
 
-.. toctree::
-   :maxdepth: 2
-
-   readme
-
-Documentation
-=============
-
-.. toctree::
-   :maxdepth: 2
-
-   modules
-
-Contributing
-============
-
-.. toctree::
-   :maxdepth: 2
-
-   contributing
-
-Other
-=====
-.. toctree::
-   :maxdepth: 1
-
-   history
-
-..
-   (removed because it is contained in the new spinx style)
-   Indices and tables
-   ==================
-   * :ref:`genindex`
-   * :ref:`modindex`
-   * :ref:`search`
+.. include:: header.rst