Merge pull request #66 from quant-aq/dhhagan-docs

Updated docs to include google-ish formatted docstrings and improved guides
quant-aq · Jul 13, 2023 · e929d72 · e929d72
2 parents b87c92a + 1b3999d
commit e929d72
Show file tree

Hide file tree

Showing 414 changed files with 37,677 additions and 391 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -30,7 +30,6 @@ jobs:
                 source .venv/bin/activate 
                 cd docs
                 make clean
-                make guides
                 make html
                 cd ..
 

diff --git a/.github/workflows/test-and-report.yml b/.github/workflows/test-and-report.yml
@@ -1,4 +1,4 @@
-name: run tests and report results
+name: ci.tests
 on: [pull_request, workflow_dispatch]
 jobs:
     tests:

diff --git a/README.md b/README.md
@@ -1,34 +1,19 @@
 [![PyPI version](https://badge.fury.io/py/py-smps.svg)](https://badge.fury.io/py/py-smps)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Coverage Status](https://coveralls.io/repos/github/dhhagan/py-smps/badge.svg?branch=master)](https://coveralls.io/github/dhhagan/py-smps?branch=master)
+[![ci.tests](https://github.com/quant-aq/py-smps/actions/workflows/test-and-report.yml/badge.svg)](https://github.com/quant-aq/py-smps/actions/workflows/test-and-report.yml)
 
 
 # py-smps
-Python library for the analysis and visualization of data from a Scanning Mobility Particle Sizer (SMPS) and other particle sizing instruments (SEMS, OPC's).
 
-## Dependencies
+py-smps is a Python data analysis library built for analyzing size-resolved aerosol data from a variety of aerosol sizing instruments (e.g., Scanning Mobility Particle Sizer, Optical Particle Counters).
 
-The full list of dependencies can be found in the `pyproject.toml` file and are summarized below:
 
-```py
-python = ">=3.8, <3.12"
-statsmodels = "^0.13"
-seaborn = "^0.10"
-joblib = "^1.0"
-requests = "^2.24"
-scipy = "^1.9"
-numpy = "^1.23.2"
-pandas = "^1.4"
-```
-
-As of `v1.2.0a0`, the library should be compatible with Apple silicone (tested on both M1 and M2).
-
-## Python Versions
+**NOTE: As of `v1.2.0`, the library is compatible with Apple silicone (M1, M2 chips).**
 
-Python3.8 through Python3.11 are currently supported.
+# Installation
 
-## Installation
-
-To install from PyPi:
+Official releases of `py-smps` can be installed from [PyPI](https://pypi.org/project/py-smps/):
 
     $ pip install py-smps [--upgrade]
 
@@ -40,39 +25,45 @@ To install the edge release directly from GitHub:
 
     pip install git+https://github.com/quant-aq/py-smps.git
 
-## Unittests
+# Dependencies
 
-Unittests can be run by issuing the following command from within the main repo:
+## Supported Python versions
+- Python 3.8+
 
-```sh
-$ poetry run pytest -s tests/ --ignore=tests/datafiles
-```
+## Mandatory Dependencies
+
+The full list of dependencies can be found in the [`pyproject.toml`](pyproject.toml) file.
 
+# Development
 
-## Documentation
+## Testing
 
-Documentation is available [here](https://quant-aq.github.io/py-smps/). Docs are built using Sphinx and can be built locally by doing the following:
+Tests can be run by issuing the following command from within the main repo:
 
 ```sh
-$ cd docs/
-$ make clean
-$ make guides
-$ make html
-$ cd ..
+$ poetry run pytest -s tests/ --ignore=tests/datafiles
 ```
 
-Then, you can navigate to your local directory at `docs/_build/html/` and open up the `index.html` file in your preferred browser window.
-
-
 ## Contributing to Development
 
 We welcome all contributions from the community in the form of issues reporting, feature requests, bug fixes, etc.
 
 If there is a feature you would like to see or a bug you would like to report, please open an issue. We will try to get to things as promptly as possible. Otherwise, feel free to send PR's!
 
 
-## Colorbar Information
+# Documentation
+
+Documentation is available [here](https://quant-aq.github.io/py-smps/). To build locally, you must first install [pandoc](https://pandoc.org/). Docs are built using Sphinx and can be built locally by doing the following:
+
+```sh
+# Activate the virtualenv
+$ poetry shell
 
-  * [matplotlib colorbars](http://matplotlib.org/examples/color/colormaps_reference.html)
-  * [seaborn color palette](http://seaborn.pydata.org/tutorial/color_palettes.html)
+# Build the docs
+$ cd docs/
+$ make clean
+$ make html
+$ cd ..
+```
 
+Then, you can navigate to your local directory at `docs/build/html/` and open up the `index.html` file in your preferred browser window.
diff --git a/docs-archived/Makefile b/docs-archived/Makefile
@@ -0,0 +1,24 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: guides
+guides:
+	make -C guides/
diff --git a/docs-archived/_build/doctrees/api/generated/smps.GenericParticleSizer.doctree b/docs-archived/_build/doctrees/api/generated/smps.GenericParticleSizer.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.fit.LogNormal.doctree b/docs-archived/_build/doctrees/api/generated/smps.fit.LogNormal.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.fit.LogNormalFitResults.doctree b/docs-archived/_build/doctrees/api/generated/smps.fit.LogNormalFitResults.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.io.load_sample.doctree b/docs-archived/_build/doctrees/api/generated/smps.io.load_sample.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.io.smps_from_txt.doctree b/docs-archived/_build/doctrees/api/generated/smps.io.smps_from_txt.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.models.AlphasenseOPCN2.doctree b/docs-archived/_build/doctrees/api/generated/smps.models.AlphasenseOPCN2.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.models.AlphasenseOPCN3.doctree b/docs-archived/_build/doctrees/api/generated/smps.models.AlphasenseOPCN3.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.models.GenericParticleSizer.doctree b/docs-archived/_build/doctrees/api/generated/smps.models.GenericParticleSizer.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.models.Grimm11D.doctree b/docs-archived/_build/doctrees/api/generated/smps.models.Grimm11D.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.models.Modulair.doctree b/docs-archived/_build/doctrees/api/generated/smps.models.Modulair.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.models.ModulairPM.doctree b/docs-archived/_build/doctrees/api/generated/smps.models.ModulairPM.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.models.POPS.doctree b/docs-archived/_build/doctrees/api/generated/smps.models.POPS.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.models.ParticlesPlus.doctree b/docs-archived/_build/doctrees/api/generated/smps.models.ParticlesPlus.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.models.SMPS.doctree b/docs-archived/_build/doctrees/api/generated/smps.models.SMPS.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.plots.heatmap.doctree b/docs-archived/_build/doctrees/api/generated/smps.plots.heatmap.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.plots.histplot.doctree b/docs-archived/_build/doctrees/api/generated/smps.plots.histplot.doctree
diff --git a/docs-archived/_build/doctrees/api/generated/smps.utils.make_bins.doctree b/docs-archived/_build/doctrees/api/generated/smps.utils.make_bins.doctree
diff --git a/docs-archived/_build/doctrees/api/index.doctree b/docs-archived/_build/doctrees/api/index.doctree
diff --git a/docs-archived/_build/doctrees/contributing/index.doctree b/docs-archived/_build/doctrees/contributing/index.doctree
diff --git a/docs-archived/_build/doctrees/contributing/issues.doctree b/docs-archived/_build/doctrees/contributing/issues.doctree
diff --git a/docs-archived/_build/doctrees/contributing/patches.doctree b/docs-archived/_build/doctrees/contributing/patches.doctree
diff --git a/docs-archived/_build/doctrees/contributing/support.doctree b/docs-archived/_build/doctrees/contributing/support.doctree
diff --git a/docs-archived/_build/doctrees/contributing/tests.doctree b/docs-archived/_build/doctrees/contributing/tests.doctree
diff --git a/docs-archived/_build/doctrees/environment.pickle b/docs-archived/_build/doctrees/environment.pickle
diff --git a/docs-archived/_build/doctrees/guides/curve_fitting.doctree b/docs-archived/_build/doctrees/guides/curve_fitting.doctree
diff --git a/docs-archived/_build/doctrees/guides/faq.doctree b/docs-archived/_build/doctrees/guides/faq.doctree
diff --git a/docs-archived/_build/doctrees/guides/general_usage.doctree b/docs-archived/_build/doctrees/guides/general_usage.doctree
diff --git a/docs-archived/_build/doctrees/guides/getting_started.doctree b/docs-archived/_build/doctrees/guides/getting_started.doctree
diff --git a/docs-archived/_build/doctrees/guides/index.doctree b/docs-archived/_build/doctrees/guides/index.doctree
diff --git a/docs-archived/_build/doctrees/index.doctree b/docs-archived/_build/doctrees/index.doctree
diff --git a/docs-archived/_build/doctrees/usage/api.doctree b/docs-archived/_build/doctrees/usage/api.doctree
diff --git a/docs-archived/_build/doctrees/usage/guide.doctree b/docs-archived/_build/doctrees/usage/guide.doctree
diff --git a/docs-archived/_build/html/.buildinfo b/docs-archived/_build/html/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 88c7c1ce5590a768c17125b66aee50df
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/...urve_fitting_files/curve_fitting_15_0.png → ...build/html/_images/curve_fitting_15_0.png b/...urve_fitting_files/curve_fitting_15_0.png → ...build/html/_images/curve_fitting_15_0.png
diff --git a/...urve_fitting_files/curve_fitting_17_0.png → ...build/html/_images/curve_fitting_17_0.png b/...urve_fitting_files/curve_fitting_17_0.png → ...build/html/_images/curve_fitting_17_0.png
diff --git a/...urve_fitting_files/curve_fitting_21_0.png → ...build/html/_images/curve_fitting_21_0.png b/...urve_fitting_files/curve_fitting_21_0.png → ...build/html/_images/curve_fitting_21_0.png
diff --git a/...urve_fitting_files/curve_fitting_23_1.png → ...build/html/_images/curve_fitting_23_1.png b/...urve_fitting_files/curve_fitting_23_1.png → ...build/html/_images/curve_fitting_23_1.png
diff --git a/...curve_fitting_files/curve_fitting_3_0.png → ..._build/html/_images/curve_fitting_3_0.png b/...curve_fitting_files/curve_fitting_3_0.png → ..._build/html/_images/curve_fitting_3_0.png
diff --git a/...curve_fitting_files/curve_fitting_7_0.png → ..._build/html/_images/curve_fitting_7_0.png b/...curve_fitting_files/curve_fitting_7_0.png → ..._build/html/_images/curve_fitting_7_0.png
diff --git a/docs/images/fitfig.png → docs-archived/_build/html/_images/fitfig.png b/docs/images/fitfig.png → docs-archived/_build/html/_images/fitfig.png
diff --git a/...eneral_usage_files/general_usage_37_1.png → ...build/html/_images/general_usage_37_1.png b/...eneral_usage_files/general_usage_37_1.png → ...build/html/_images/general_usage_37_1.png
diff --git a/...eneral_usage_files/general_usage_39_0.png → ...build/html/_images/general_usage_39_0.png b/...eneral_usage_files/general_usage_39_0.png → ...build/html/_images/general_usage_39_0.png
diff --git a/...eneral_usage_files/general_usage_41_0.png → ...build/html/_images/general_usage_41_0.png b/...eneral_usage_files/general_usage_41_0.png → ...build/html/_images/general_usage_41_0.png
diff --git a/docs/images/heatmap.png → ...-archived/_build/html/_images/heatmap.png b/docs/images/heatmap.png → ...-archived/_build/html/_images/heatmap.png
diff --git a/docs/images/histogram.png → ...rchived/_build/html/_images/histogram.png b/docs/images/histogram.png → ...rchived/_build/html/_images/histogram.png
diff --git a/docs/images/multihistogram.png → ...ed/_build/html/_images/multihistogram.png b/docs/images/multihistogram.png → ...ed/_build/html/_images/multihistogram.png
diff --git a/...i/generated/smps.GenericParticleSizer.rst → ...nerated/smps.GenericParticleSizer.rst.txt b/...i/generated/smps.GenericParticleSizer.rst → ...nerated/smps.GenericParticleSizer.rst.txt
diff --git a/docs/api/generated/smps.fit.LogNormal.rst → .../api/generated/smps.fit.LogNormal.rst.txt b/docs/api/generated/smps.fit.LogNormal.rst → .../api/generated/smps.fit.LogNormal.rst.txt
diff --git a/...enerated/smps.fit.LogNormalFitResults.rst → ...ated/smps.fit.LogNormalFitResults.rst.txt b/...enerated/smps.fit.LogNormalFitResults.rst → ...ated/smps.fit.LogNormalFitResults.rst.txt
diff --git a/docs/api/generated/smps.io.load_sample.rst → ...api/generated/smps.io.load_sample.rst.txt b/docs/api/generated/smps.io.load_sample.rst → ...api/generated/smps.io.load_sample.rst.txt
diff --git a/docs/api/generated/smps.io.smps_from_txt.rst → ...i/generated/smps.io.smps_from_txt.rst.txt b/docs/api/generated/smps.io.smps_from_txt.rst → ...i/generated/smps.io.smps_from_txt.rst.txt
diff --git a/...generated/smps.models.AlphasenseOPCN2.rst → ...rated/smps.models.AlphasenseOPCN2.rst.txt b/...generated/smps.models.AlphasenseOPCN2.rst → ...rated/smps.models.AlphasenseOPCN2.rst.txt
diff --git a/...generated/smps.models.AlphasenseOPCN3.rst → ...rated/smps.models.AlphasenseOPCN3.rst.txt b/...generated/smps.models.AlphasenseOPCN3.rst → ...rated/smps.models.AlphasenseOPCN3.rst.txt
diff --git a/...ated/smps.models.GenericParticleSizer.rst → .../smps.models.GenericParticleSizer.rst.txt b/...ated/smps.models.GenericParticleSizer.rst → .../smps.models.GenericParticleSizer.rst.txt
diff --git a/docs/api/generated/smps.models.Grimm11D.rst → ...pi/generated/smps.models.Grimm11D.rst.txt b/docs/api/generated/smps.models.Grimm11D.rst → ...pi/generated/smps.models.Grimm11D.rst.txt
diff --git a/docs/api/generated/smps.models.Modulair.rst → ...pi/generated/smps.models.Modulair.rst.txt b/docs/api/generated/smps.models.Modulair.rst → ...pi/generated/smps.models.Modulair.rst.txt
diff --git a/.../api/generated/smps.models.ModulairPM.rst → .../generated/smps.models.ModulairPM.rst.txt b/.../api/generated/smps.models.ModulairPM.rst → .../generated/smps.models.ModulairPM.rst.txt
diff --git a/docs/api/generated/smps.models.POPS.rst → ...es/api/generated/smps.models.POPS.rst.txt b/docs/api/generated/smps.models.POPS.rst → ...es/api/generated/smps.models.POPS.rst.txt
diff --git a/...i/generated/smps.models.ParticlesPlus.rst → ...nerated/smps.models.ParticlesPlus.rst.txt b/...i/generated/smps.models.ParticlesPlus.rst → ...nerated/smps.models.ParticlesPlus.rst.txt
diff --git a/docs/api/generated/smps.models.SMPS.rst → ...es/api/generated/smps.models.SMPS.rst.txt b/docs/api/generated/smps.models.SMPS.rst → ...es/api/generated/smps.models.SMPS.rst.txt
diff --git a/docs/api/generated/smps.plots.heatmap.rst → .../api/generated/smps.plots.heatmap.rst.txt b/docs/api/generated/smps.plots.heatmap.rst → .../api/generated/smps.plots.heatmap.rst.txt
diff --git a/docs/api/generated/smps.plots.histplot.rst → ...api/generated/smps.plots.histplot.rst.txt b/docs/api/generated/smps.plots.histplot.rst → ...api/generated/smps.plots.histplot.rst.txt
diff --git a/docs/api/generated/smps.utils.make_bins.rst → ...pi/generated/smps.utils.make_bins.rst.txt b/docs/api/generated/smps.utils.make_bins.rst → ...pi/generated/smps.utils.make_bins.rst.txt
diff --git a/docs/api/index.rst → ...ed/_build/html/_sources/api/index.rst.txt b/docs/api/index.rst → ...ed/_build/html/_sources/api/index.rst.txt
diff --git a/docs/contributing/index.rst → .../html/_sources/contributing/index.rst.txt b/docs/contributing/index.rst → .../html/_sources/contributing/index.rst.txt
diff --git a/docs/contributing/issues.md → .../html/_sources/contributing/issues.md.txt b/docs/contributing/issues.md → .../html/_sources/contributing/issues.md.txt
diff --git a/docs/contributing/patches.md → ...html/_sources/contributing/patches.md.txt b/docs/contributing/patches.md → ...html/_sources/contributing/patches.md.txt
diff --git a/docs/contributing/support.md → ...html/_sources/contributing/support.md.txt b/docs/contributing/support.md → ...html/_sources/contributing/support.md.txt
diff --git a/docs/contributing/tests.md → ...d/html/_sources/contributing/tests.md.txt b/docs/contributing/tests.md → ...d/html/_sources/contributing/tests.md.txt
diff --git a/docs/guides/curve_fitting.rst → ...tml/_sources/guides/curve_fitting.rst.txt b/docs/guides/curve_fitting.rst → ...tml/_sources/guides/curve_fitting.rst.txt
diff --git a/docs/guides/faq.md → ...ed/_build/html/_sources/guides/faq.md.txt b/docs/guides/faq.md → ...ed/_build/html/_sources/guides/faq.md.txt
diff --git a/docs/guides/general_usage.rst → ...tml/_sources/guides/general_usage.rst.txt b/docs/guides/general_usage.rst → ...tml/_sources/guides/general_usage.rst.txt
diff --git a/docs/guides/getting_started.md → ...ml/_sources/guides/getting_started.md.txt b/docs/guides/getting_started.md → ...ml/_sources/guides/getting_started.md.txt
diff --git a/docs/guides/index.rst → ..._build/html/_sources/guides/index.rst.txt b/docs/guides/index.rst → ..._build/html/_sources/guides/index.rst.txt
diff --git a/docs/index.rst → ...chived/_build/html/_sources/index.rst.txt b/docs/index.rst → ...chived/_build/html/_sources/index.rst.txt
diff --git a/docs/usage/api.rst → ...ed/_build/html/_sources/usage/api.rst.txt b/docs/usage/api.rst → ...ed/_build/html/_sources/usage/api.rst.txt
diff --git a/docs/usage/guide.rst → .../_build/html/_sources/usage/guide.rst.txt b/docs/usage/guide.rst → .../_build/html/_sources/usage/guide.rst.txt