got all documentation read for readthedocs

.gitignore

@@ -40,6 +40,7 @@ result_images
 # Sphinx documentation
 doc/_build/
 .buildinfo
+docs/source/_auto_examples/
 
 # Jupyter Notebook
 .ipynb_checkpoints

docs/source/conf.py

@@ -12,42 +12,95 @@
 
 import os
 import sys
+import warnings
 sys.path.insert(0, os.path.abspath('../..'))
 
 
 # -- Project information -----------------------------------------------------
 
 project = 'pyhydrophone'
-copyright = '2020, Clea Parcerisas'
+copyright = '2023, Clea Parcerisas'
 author = 'Clea Parcerisas'
 
+# The full version, including alpha/beta/rc tags
+# pypam_version = SourceFileLoader('pyhydrophone.version',
+#                                 '../pyhydrophone/version.py').load_module()
+
+# release = pyhydrophone_version.__version__
+# version = pyhydrophone_version.__version__
+release = '0.1.6'
+version = '0.1.6'
+
 
 # -- General configuration ---------------------------------------------------
 
 # 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.coverage', 'sphinx.ext.napoleon']
+extensions = ['sphinx.ext.autodoc',  # Core Sphinx library for auto html doc generation from docstrings
+              'sphinx.ext.autosummary',  # Create neat summary tables for modules/classes/methods etc
+              'sphinx.ext.intersphinx',  # Link to other project's documentation (see mapping below)
+              'sphinx.ext.viewcode',  # Add a link to the Python source code for classes, functions etc.
+              # 'sphinx_autodoc_typehints',  # Automatically document param types (less noise in class signature)
+              'sphinx.ext.githubpages',
+              'numpydoc',  # docstring examples
+              'sphinx.ext.autosectionlabel',
+              'sphinx_gallery.gen_gallery',
+              ]
+
+
+html4_writer = True
+autosummary_generate = True
+
+# -- Example Gallery --
+sphinx_gallery_conf = {
+    'examples_dirs': '../../examples',  # path to your example scripts
+    'gallery_dirs': '_auto_examples',  # path to where to save gallery generated output,
+    'capture_repr': (),
+    # define which output is captured https://sphinx-gallery.github.io/stable/configuration.html#capture-repr
+    'ignore_repr_types': r'matplotlib[text, axes]',
+}
+warnings.filterwarnings("ignore", category=UserWarning,
+                        message='Matplotlib is currently using agg, which is a'
+                                ' non-GUI backend, so cannot show the figure.')
+
+numpydoc_show_class_members = False
+
+# Mappings for sphinx.ext.intersphinx. Projects have to have Sphinx-generated doc! (.inv file)
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+}
+
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
+autoclass_content = "both"  # Add __init__ doc (ie. params) to class summaries
+# html_show_sourcelink = False  # Remove 'view source code' from top of page (for html, not python)
+autodoc_inherit_docstrings = True  # If no class summary, inherit base class summary
+
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 
 # -- Options for HTML output -------------------------------------------------
+import sphinx_rtd_theme
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # 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']
 
-master_doc = 'contents'
+# If false, no module index is generated.
+html_domain_indices = True
+# If false, no index is generated.
+html_use_index = True
+html_use_modindex = True

docs/source/index.rst

@@ -0,0 +1,73 @@
+pyhydrophone |version|
+======================
+
+Description
+-----------
+pyhydrophone helps keeping together all the information of the recorder.
+It makes it easier to read different hydrophones' output files and extract the information.
+
+Each class represents a different hydrophone. The available ones now are (others will be added):
+
+* SoundTrap (OceanInstruments)
+* Seiche (Seiche)
+* AMAR (JASCO)
+* RESEA (RTSys)
+* uPAM (Seiche)
+* EARS
+* MTE AURAL (MTE)
+
+
+They all inherit from the main class Hydrophone.
+If a certain recorder provides an output different than a regular wav file, functions to read and understand the output
+are provided.
+Functions to read the metadata are also provided (which is often encoded in the file name).
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Getting Started
+
+   install
+   quickstart
+
+.. toctree::
+   :caption: Hydrophone objects
+   :maxdepth: 1
+
+   data_structures
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Example Gallery
+
+   _auto_examples/index
+
+
+Citing pyhydrophone
+~~~~~~~~~~~~~~~~~~~
+
+.. note::
+  If you find this package useful in your research, we would appreciate citations to:
+
+Parcerisas (2023). lifewatch/pyhydrophone: A package to deal with hydrophone data. Zenodo.
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7588428.svg)](https://doi.org/10.5281/zenodo.7588428)
+
+
+
+
+About the project
+~~~~~~~~~~~~~~~~~
+This project has been funded by `LifeWatch Belgium <https://www.lifewatch.be/>`_.
+
+.. image:: _static/lw_logo.png
+
+
+For any questions please relate to [email protected]
+
+
+Indices and tables
+~~~~~~~~~~~~~~~~~~
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/install.rst

@@ -0,0 +1,34 @@
+.. currentmodule:: pyhydrophone
+
+Install
+=======
+
+Using pip distribution
+----------------------
+.. code-block::
+
+    pip install pyhydrophone
+
+
+Using git clone
+---------------
+
+1. Clone the package
+
+.. code-block::
+
+    git clone https://github.com/lifewatch/pyhydrophone.git
+
+
+2. Use poetry to install the project dependencies
+
+.. code-block::
+
+    poetry install
+
+
+3. Build the project
+
+.. code-block::
+
+    poetry build

docs/source/quickstart.rst

@@ -0,0 +1,58 @@
+.. currentmodule:: pyhydrophone
+
+Introduction to pyhydrophone
+============================
+
+Passive acoustics monitoring is becoming more and more popular in marine environments.
+Therefore, more and more underwater acoustic recorders can be found in the market. However, the output they give is not
+standardized and each of them usually needs an if statement.
+pyhydrophone is thus thought as a package which can be used in data analysis pipelines or scripts without having to
+change the way the metadata is read for a different recorder.
+
+First, an object is created to represent a hydrophone with all its metadata::
+
+    import pyhydrophone as pyhy
+
+    # SoundTrap
+    model = 'SoundTrap 300 STD'
+    name = 'SoundTrap'
+    serial_number = 67416073
+    soundtrap = pyhy.soundtrap.SoundTrap(name=name, model=model, serial_number=serial_number)
+
+
+Then this object can be used in a pipeline in a way such as::
+
+    wav_path = 'tests/test_data/soundtrap/67416073.210610033655.wav'
+    start_datetime_of_wav = soundtrap.get_name_datetime(wav_path)
+
+
+It can also be used to for calibration::
+
+    import soundfile as sf
+    import numpy as np
+
+    wav = sf.read(wav_path)
+    rms_db = 10 * np.log10(np.mean(wav**2))
+    rms_db_upa = rms_db + soundtrap.end_to_end_calibration()
+
+
+If you have a frequency dependent calibration file, it can also be used::
+
+    import scipy.signal as sig
+
+    rtsys_name = 'RTSys'
+    rtsys_model = 'RESEA320'
+    rtsys_serial_number = 2003001
+    rtsys_sens = -180
+    rtsys_preamp = 0
+    rtsys_vpp = 5
+    mode = 'lowpower'
+    calibration_file = pathlib.Path("tests/test_data/rtsys/SN130.csv")
+    rtsys = pyhy.RTSys(name=rtsys_name, model=rtsys_model, serial_number=rtsys_serial_number, sensitivity=rtsys_sens,preamp_gain=rtsys_preamp, Vpp=rtsys_vpp, mode=mode, calibration_file=calibration_file)
+
+    wav_path = 'tests/test_data/rtsys/channelA_2021-10-11_13-11-09.wav'
+    wav, fs = sf.read(wav_path)
+    frequencies, spectrum = sig.welch(wav)
+    frequency_increment = rtsys.freq_cal_inc(frequencies)
+    print(df)
+

examples/README.rst

@@ -0,0 +1,4 @@
+Example gallery
+===============
+
+This gallery is intended to present examples on how to use pyhydrophone.