Merge pull request #73 from v0lta/improved-docs

Improved docs
v0lta · Mar 22, 2024 · 1312399 · 1312399
2 parents 38901ce + 2cdd64c
commit 1312399
Show file tree

Hide file tree

Showing 37 changed files with 751 additions and 93 deletions.
diff --git a/.flake8 b/.flake8
@@ -37,7 +37,7 @@ exclude =
     .eggs,
     data.
     src/ptwt/__init__.py
-max-line-length = 88
+max-line-length = 90
 max-complexity = 20
 import-order-style = pycharm
 application-import-names =

diff --git a/CITATION.bib b/CITATION.bib
@@ -15,4 +15,4 @@ @thesis{Blanke2021
   annote        = {Gbachelor},
   year          = {2021},
   school        = {Institut f\"ur Numerische Simulation, Universit\"at Bonn}
-}
+}
diff --git a/README.rst b/README.rst
@@ -51,14 +51,15 @@ Welcome to the PyTorch wavelet toolbox. This package implements:
 This toolbox extends `PyWavelets <https://pywavelets.readthedocs.io/en/latest/>`_. In addition to boundary wavelets, we provide GPU and gradient support via a PyTorch backend.
 Complete documentation is available at: https://pytorch-wavelet-toolbox.readthedocs.io/en/latest/ptwt.html
 
+This toolbox is independent work. Meta or the PyTorch team have not endorsed it.
 
 **Installation**
 
 Install the toolbox via pip or clone this repository. In order to use ``pip``, type:
 
 .. code-block:: sh
 
-    $ pip install ptwt
+    pip install ptwt
   
 
 You can remove it later by typing ``pip uninstall ptwt``.
@@ -158,7 +159,7 @@ Reconsidering the 1d case, try:
 The process for the 2d transforms ``MatrixWavedec2``, ``MatrixWaverec2`` works similarly.
 By default, a separable transformation is used.
 To use a non-separable transformation, pass ``separable=False`` to ``MatrixWavedec2`` and ``MatrixWaverec2``.
-Separable transformations use a 1d transformation along both axes, which might be faster since fewer matrix entries
+Separable transformations use a 1D transformation along both axes, which might be faster since fewer matrix entries
 have to be orthogonalized.
 
 
@@ -181,11 +182,11 @@ After cloning the repository, moving into the main directory, and installing ``n
 
 .. code-block:: sh
 
-  $ nox --session test
+  nox --session test
 
 
 
-to run all existing tests.
+for all existing tests.
 
 Citation
 """"""""
@@ -194,25 +195,9 @@ If you use this work in a scientific context, please cite the following:
 
 .. code-block::
 
-  @phdthesis{handle:20.500.11811/9245,
-    author = {{Moritz Wolter}},
-    title = {Frequency Domain Methods in Recurrent Neural Networks for Sequential Data Processing},
-    school = {Rheinische Friedrich-Wilhelms-Universität Bonn},
-    year = 2021,
-    month = jul,
-    url = {https://hdl.handle.net/20.500.11811/9245}
-  }
-
-If you use the boundary wavelet support, please additionally cite:
-
-.. code-block::
-
-  @thesis{Blanke2021,
-    author = {Felix Blanke},
-    title = {{Randbehandlung bei Wavelets für Faltungsnetzwerke}},
-    type = {Bachelor's Thesis},
-    annote = {Gbachelor},
-    year = {2021},
-    school = {Institut f\"ur Numerische Simulation, Universit\"at Bonn}
-  }
-
+  @article{ptwt_2023, 
+    author = {Wolter, Moritz and Blanke, Felix and Garcke, Jochen and Hoyt, Charles Tapley},
+    title = {ptwt - The PyTorch Wavelet Toolbox},
+    journal = {Journal of Machine Learning Research},
+    year = {2023}
+    }
diff --git a/docs/favicon/favicon.ico → docs/_static/favicon.ico b/docs/favicon/favicon.ico → docs/_static/favicon.ico
diff --git a/docs/_static/shannon.png b/docs/_static/shannon.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -19,9 +19,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "PyTorch-Wavelet-Toolbox"
-copyright = "2022, Moritz Wolter"
-author = "Moritz Wolter"
-
+copyright = "2024, the ptwt-team"
 
 # -- General configuration ---------------------------------------------------
 
@@ -32,9 +30,11 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
     "sphinx.ext.todo",
     "sphinx.ext.coverage",
     "sphinx.ext.viewcode",
+    "sphinxcontrib.bibtex",
 ]
 
 napoleon_google_docstring = True
@@ -58,28 +58,27 @@
 # a list of builtin themes.
 #
 
-html_theme = "alabaster"
-html_sidebars = {
-    "**": [
-        "about.html",
-        "navigation.html",
-        "searchbox.html",
-    ]
-}
+html_theme = "sphinx_book_theme"
 
 html_theme_options = {
-    "github_user": "v0lta",
-    "github_repo": "PyTorch-Wavelet-Toolbox",
-    "github_banner": "false",
-    "show_related": "true",
-    "page_width": "auto",
-    "sidebar_width": "250px",
+    "show_toc_level": 2,
+    "repository_url": "https://github.com/v0lta/PyTorch-Wavelet-Toolbox",
+    "use_repository_button": True,
+    "navigation_with_keys": False,
 }
 
+html_favicon = "_static/favicon.ico"
+html_logo = "_static/shannon.png"
 
 html_favicon = "favicon/favicon.ico"
 
 # 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"]
+
+
+bibtex_bibfiles = ["literature.bib"]
+
+# numbered figures
+numfig = True
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -0,0 +1,5 @@
+Wavelet transforms by example
+=============================
+
+Worked examples are available in the examples folder of the `GitHub repository <https://github.com/v0lta/PyTorch-Wavelet-Toolbox/tree/main/examples>`_ .
+
diff --git a/docs/figures/convert.sh b/docs/figures/convert.sh
@@ -0,0 +1 @@
+convert -density 250 fwt.pdf -quality 100 fwt.png
diff --git a/docs/figures/db6.pdf b/docs/figures/db6.pdf
diff --git a/docs/figures/db6.png b/docs/figures/db6.png
diff --git a/docs/figures/fwt.pdf b/docs/figures/fwt.pdf
diff --git a/docs/figures/fwt.png b/docs/figures/fwt.png
diff --git a/docs/figures/fwt_2d.pdf b/docs/figures/fwt_2d.pdf
diff --git a/docs/figures/fwt_2d.png b/docs/figures/fwt_2d.png
diff --git a/docs/figures/packets_1d.pdf b/docs/figures/packets_1d.pdf
diff --git a/docs/figures/packets_1d.png b/docs/figures/packets_1d.png
diff --git a/docs/figures/packets_2d.pdf b/docs/figures/packets_2d.pdf
diff --git a/docs/figures/packets_2d.png b/docs/figures/packets_2d.png
diff --git a/docs/figures/sym6.pdf b/docs/figures/sym6.pdf
diff --git a/docs/figures/sym6.png b/docs/figures/sym6.png
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,28 +3,65 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+.. _PyTorch install instructions: https://pytorch.org/get-started/locally/
 
+PyTorch Wavelet Toolbox (``ptwt``)
+==================================
 
-.. include:: ../README.rst
+``ptwt`` brings wavelet transforms to PyTorch. The code is open-source, follow the link above
+to go to the source. This package is listed in the Python Package Index (PyPI). Its best installed via pip.
+GPU support depends on PyTorch. To take advantage of GPU-processing follow the `PyTorch install instructions`_.
+Install the version that best suits your systems hardware setup. Once PyTorch ist set up, type the following
+to get started:
 
+.. code-block:: sh
 
+    pip install ptwt
 
-Full documentation
-==================
+This documentation aims to explain the foundations of wavelet theory, introduce the ``ptwt`` package by example, and
+deliver a complete documentation of all functions. Readers who are already familiar with the theory should directly
+jump to the examples or the API-documentation using the navigation on the left.
 
-Use the ptwt package link below to jump to the documentation of all functions.
+``ptwt`` is built to be `PyWavelets <https://pywavelets.readthedocs.io/en/latest/>`_ compatible.
+It should be possible to switch back and forth with relative ease.
+
+If you use this work in a scientific context, please cite the following thesis:
+
+.. code-block::
+
+   @phdthesis{handle:20.500.11811/9245,
+   urn: https://nbn-resolving.org/urn:nbn:de:hbz:5-63361,
+   author = {{Moritz Wolter}},
+   title = {Frequency Domain Methods in Recurrent Neural Networks for Sequential Data Processing},
+   school = {Rheinische Friedrich-Wilhelms-Universität Bonn},
+   year = 2021,
+   month = jul,
+   url = {https://hdl.handle.net/20.500.11811/9245}
+   }
+
+   @thesis{Blanke2021,
+   author        = {Felix Blanke},
+   title         = {{Randbehandlung bei Wavelets für Faltungsnetzwerke}},
+   type          = {Bachelor's Thesis},
+   annote        = {Gbachelor},
+   year          = {2021},
+   school        = {Institut f\"ur Numerische Simulation, Universit\"at Bonn}
+   }
 
 .. toctree::
-   :maxdepth: 2
-   :caption: ptwt module overview:
+   :hidden:
+   :maxdepth: 1
+   :caption: Getting Started
 
-   ptwt
+   intro
+   intro_cwt
+   examples
 
 
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :caption: Public API
 
-Indices and tables
-==================
+   ptwt
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`