Finalize basic docs

README.md

@@ -8,6 +8,54 @@ Echo State Networks powered by
 and
 [dask](https://www.dask.org/).
 
+## Description
+
+**xesn** is a python package for implementing Echo State Networks (ESNs), a
+particular form of Recurrent Neural Network originally introduced by
+[Jaeger (2001)](https://www.ai.rug.nl/minds/uploads/EchoStatesTechRep.pdf).
+The main purpose of the package is to enable ESNs for relatively large scale
+weather and climate applications,
+for example as by [Smith et al., (2023)](https://arxiv.org/abs/2305.00100)
+and [Arcomano et al., (2020)](https://doi.org/10.1029/2020GL087776).
+The package is designed to strike the balance between simplicity and
+flexibility, with a focus on implementing features that were shown to matter
+most by [Platt et al., (2022)](https://doi.org/10.1016/j.neunet.2022.06.025).
+
+xesn uses [xarray](https://docs.xarray.dev/en/stable/)
+to handle multi-dimensional data, relying on
+[dask](https://www.dask.org/) for parallelization and
+to handle datasets/networks that are too large for a single compute node.
+At its core, xesn uses
+[numpy](https://numpy.org/)
+and [cupy](https://cupy.dev/)
+for efficient CPU and GPU deployment.
+
+## Installation
+
+To install from source
+
+```shell
+git clone https://github.com/timothyas/xesn.git
+cd xesn
+pip install -e .
+```
+
+Note that additional dependencies can be installed to run the unit test suite::
+
+```shell
+pip install -e .[test]
+pytest xesn/test/*.py
+```
+
+## Getting Started
+
+To learn how to use xesn, check out the
+[documentation here](https://xesn.readthedocs.io/en/latest/index.html)
+
+## Get in touch
+
+Report bugs, suggest features, or view the source code
+[on GitHub](https://github.com/timothyas/xesn).
 
 ## License and Copyright
 

ci/environment.yaml

@@ -20,4 +20,4 @@ dependencies:
     - coverage
     - pip
     - pip:
-        - smt>=2.0.1
+        - smt==2.1.0

docs/contributing.rst

@@ -0,0 +1,74 @@
+How to Contribute
+#################
+
+If you're interested in contributing to xesn, thank you! Here are some pointers
+for doing so.
+
+1. Environment Setup
+--------------------
+
+First you will want to fork the main repository, and clone that fork onto the
+machine where you'll do the development work.
+Ultimately, we want any contribution in the form of a pull request that is on
+this code fork *on a separate branch from the main branch*.
+If this is unfamiliar terminology, check out
+`this git tutorial
+<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_
+describing how to make a pull request from a fork, and also
+`this page about branches
+<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches>`_.
+
+After forking the repository, create and activate a development environment as follows::
+
+    cd xesn
+    conda env create -f docs/environment.yaml
+    conda activate xesn
+    pip install -e . --no-deps
+
+and you can test that everything went smoothly by running the unittest suite::
+
+    pytest xesn/test/*.py
+
+2. Develop Contributions
+------------------------
+
+Add those awesome contributions to your development branch.
+If you are adding a feature to the code base, then make sure to periodically run the test 
+suite as shown above::
+
+    cd xesn
+    conda activate xesn
+    pytest xesn/test/*.py
+
+Additionally, we'll want the new developments to have tests and
+`docstrings <https://peps.python.org/pep-0257/>`_
+of their own, so
+please consider writing tests and documentation during development.
+
+If you are adding to the documentation, then you'll want to first verify that
+the documentation builds locally in the environment you created::
+
+    cd xesn/docs
+    conda activate xesn
+    make html
+
+After that, you can open the generated html files to view in your web browser::
+
+    open build/html/index.html
+
+Rinse and repeat as you add your documentation :)
+
+Don't hesitate to
+`create an issue <https://github.com/timothyas/xesn/issues/new>`_
+describing the feature or documentation you're interested in adding, and any areas you might like
+some help.
+We'd be happy to discuss it and help where we can.
+
+3. Submit a Pull Request
+------------------------
+
+We recommend doing this on our repository's
+`PR webpage 
+<https://github.com/timothyas/xesn/pulls>`_
+as outlined `on this page
+<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_.

docs/index.rst

@@ -19,23 +19,40 @@ most by :cite:t:`platt_systematic_2022`.
 
 xesn uses `xarray <https://docs.xarray.dev/en/stable/>`_ 
 to handle multi-dimensional data, relying on
-`dask <https://www.dask.org/>`_ for parallelization.
+`dask <https://www.dask.org/>`_ for parallelization and
+to handle datasets/networks that are too large for a single compute node.
 At its core, xesn uses
 `numpy <https://numpy.org/>`_ 
 and `cupy <https://cupy.dev/>`_ 
 for efficient CPU and GPU deployment.
 
 
 
-
 .. toctree::
    :maxdepth: 1
+   :caption: Getting Started
 
    installation
    methods
-   example_esn_usage
-   example_lazy_usage
-   example_macro_training
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Examples
+
+   Using the Standard ESN <example_esn_usage>
+   Using the Parallel ESN <example_lazy_usage>
+   Macro Parameter Optimization <example_macro_training>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Community
+
+   contributing
+   support
+
+.. toctree::
+   :maxdepth: 1
+   :caption: References
+
    references
    api
-

docs/installation.rst

@@ -12,7 +12,8 @@ and install it as follows::
     cd xesn
     pip install -e .
 
-Note that additional dependencies can be installed to run the unit test suite::
+Note that additional dependencies can be installed to run the unit test suite
+and ensure everything is working properly::
 
     pip install -e .[test]
     pytest xesn/test/*.py

docs/methods.rst

@@ -167,21 +167,6 @@ each time step "column-wise":
 and similarly
 :math:`\mathbf{V} = (\mathbf{v}(1) \, \mathbf{v}(2) \, \cdots \, \mathbf{v}(N_{\text{train}}))`.
 
-Macro-Scale Parameters
-----------------------
-
-From our experience, the most important macro-scale parameters that must be
-specified by the user are the
-
-- input matrix scaling, :math:`\sigma`, ``input_kwargs["factor"]``
-- adjacency matrix scaling, :math:`\rho`, ``adjacency_kwargs["factor"]``
-- bias vector scaling, :math:`\sigma_b`, ``bias_kwargs["factor"]``
-- Tikhonov parameter, :math:`\beta`, ``tikhonov_parameter``
-- leak rate, :math:`\alpha`, ``leak_rate``
-
-See `this example <example_macro_training.ipynb>`_ for a demonstration of using the
-`surrogate modeling toolbox <https://smt.readthedocs.io/en/latest/index.html>`_
-to perform Bayesian optimization and find well performing parameter values.
 
 Distributed ESN Architecture
 ############################
@@ -354,3 +339,19 @@ Note that the various macro-scale paramaters
 Therefore the only components that drive unique hidden states on each chunk are
 the different input states :math:`\mathbf{u}_k` and the readout matrices
 :math:`\mathbf{W}_\text{out}^k`.
+
+Macro-Scale Parameters
+######################
+
+From our experience, the most important macro-scale parameters that must be
+specified by the user are the
+
+- input matrix scaling, :math:`\sigma`, ``input_kwargs["factor"]``
+- adjacency matrix scaling, :math:`\rho`, ``adjacency_kwargs["factor"]``
+- bias vector scaling, :math:`\sigma_b`, ``bias_kwargs["factor"]``
+- Tikhonov parameter, :math:`\beta`, ``tikhonov_parameter``
+- leak rate, :math:`\alpha`, ``leak_rate``
+
+See `this example <example_macro_training.ipynb>`_ for a demonstration of using the
+`surrogate modeling toolbox <https://smt.readthedocs.io/en/latest/index.html>`_
+to perform Bayesian optimization and find well performing parameter values.

docs/references.rst

@@ -1,4 +1,4 @@
-References
-##########
+Scientific References
+#####################
 
 .. bibliography::

docs/support.rst

@@ -0,0 +1,7 @@
+Getting Support
+###############
+
+If you think there is a bug in the code or have any questions about using xesn,
+please 
+`submit an issue <https://github.com/timothyas/xesn/issues/new>`_,
+with a sufficient description of the problem or question.

pyproject.toml

@@ -21,6 +21,7 @@ gpus = [
 ]
 
 [project.urls]
+homepage="https://github.com/timothyas/xesn"
 source="https://github.com/timothyas/xesn"
 documentation="https://xesn.readthedocs.io/en/latest/"