Merge pull request #20 from anniegbryant/docs_dev

Start Issues and FAQ page for docs
DynamicsAndNeuralSystems · Jan 10, 2023 · 03925bd · 03925bd
2 parents a4818f4 + 10541fd
commit 03925bd
Show file tree

Hide file tree

Showing 5 changed files with 135 additions and 36 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -2,12 +2,12 @@
 
 # -- Project information
 
-project = 'PySPI'
+project = 'pyspi'
 copyright = '2022, Oliver M. Cliff'
 author = 'Oliver M. Cliff'
 
-release = '0.3'
-version = '0.3.0'
+release = '0.4'
+version = '0.4.0'
 
 # -- General configuration
 

diff --git a/docs/source/faq.rst b/docs/source/faq.rst
@@ -0,0 +1,89 @@
+Issues & FAQ
+===================================
+
+
+FAQ
+########
+
+Issues 
+########
+
+
+Java JVM DLL not found (specific to Mac)
+**********************
+
+One user reported the following error when installing `pyspi` on a MacBook Air an M2 chip and Catalina OS:
+
+.. code-block::
+
+   OSError: [Errno 0] JVM DLL not found /Library/Java/JavaVirtualMachines/jdk-19.jdk/Contents/Home/lib/libjli.dylib
+
+
+This issue is similar to those reported `here <https://stackoverflow.com/questions/71504214/jvm-dll-not-found-but-i-can-clearly-see-the-file>`_ and `here <https://github.com/jpype-project/jpype/issues/994>`_; it can arise from the version of OpenJDK identified as the system default. Some Java versions don't include all of the binary (DLL) files that `pyspi` looks for.
+
+We recommend following this `helpful tutorial <https://blog.bigoodyssey.com/how-to-manage-multiple-java-version-in-macos-e5421345f6d0>`_ by Chamika Kasun to install `AdoptOpenJDK <https://adoptopenjdk.net/index.html>`_. In a nutshell, here are the steps you should run:
+
+Install homebrew if you don't already have it:
+
+.. code-block::
+
+   $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+
+Install `jenv` as your Java version manager:
+
+.. code-block:: 
+
+    $ brew install jenv
+
+
+Add `jenv` to your shell's configuration file (e.g. `.bashrc` if you use `bash`):
+
+.. code-block:: 
+
+    $ export PATH="$HOME/.jenv/bin:$PATH"
+    $ eval "$(jenv init -)"
+
+Source your shell's configuration file:
+
+.. code-block:: 
+
+    $ source ~/.bashrc # If you use bash
+
+Confirm proper installation of `jEnv`:
+
+.. code-block::
+
+    $ jenv doctor
+
+Even if this returns some errors, as long as you see `Jenv is correctly loaded`, you're all set. We recommend using `AdoptOpenJDK` version 11, which you can install with the following command:
+
+.. code-block:: 
+
+    $ brew install AdoptOpenJDK/openjdk/adoptopenjdk11
+
+Now, you will need to add your `AdoptOpenJDK` path to your `jEnv` environments. First, you can find where your jdk files are installed with the following command:
+
+.. code-block:: 
+
+    $ /usr/libexec/java_home -V
+
+This will list all your installed java JDK versions. Locate the one for `AdoptOpenJDK` version 11 and paste the path:
+
+.. code-block::
+
+    $ jenv add <path_to_adopt_open_jdk_11>
+
+Confirm `AdoptOpenJDK` version 11 was added to `jEnv`:
+
+.. code-block:: 
+
+    $ jenv versions
+
+You can set `AdoptOpenJDK` version 11 as your global Java version with the following:
+
+.. code-block:: 
+
+    $ jenv global <AdoptOpenJDK version>
+    $ # example:
+    $ jenv global 11.0
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,7 +1,7 @@
-Welcome to PySPI's documentation!
+Welcome to pyspi's documentation!
 ===================================
 
-**PySPI** (/pie'spy/) is a Python library for simultaneously evaluating hundreds of pairwise interactions directly from multivariate time-series data.
+**pyspi** (/pie'spy/) is a Python library for simultaneously evaluating hundreds of pairwise interactions directly from multivariate time-series data.
 
 It provides easy access to over 250 methods for evaluating the relationship between pairs of time series, from simple statistics (like correlation coefficients) to advanced multi-step algorithms (like Granger causality).
 
@@ -16,6 +16,8 @@ Contents
 
 .. toctree::
 
+   installation
    usage
    advanced
-   api
+   api
+   faq
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -0,0 +1,38 @@
+Installation
+===================================
+
+Pre-installation
+----------------
+
+The code requires GNU's `Octave <https://www.gnu.org/software/octave/index>`_ by default, which is freely available on all popular operating systems.
+See the `installation instructions <https://wiki.octave.org/Category:Installation>`_ to find out how to install Octave on your system.
+
+.. note::
+   You can safely install `pyspi` without first installing Octave but you will not have access to the `Integrated Information Theory` statistics, see :ref:`Using the toolkit without Octave`.
+
+While you can also install `pyspi` outside of a `conda <https://docs.conda.io/projects/conda/en/latest/index.html>`_ environment, it depends on a lot of user packages that may make managing dependencies quite difficult.
+So, we would also recommend installing `pyspi` in a conda environment.
+After `installing conda <https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html>`_, create a new environment for using the toolkit:
+
+.. code-block:: console
+
+   $ conda create -n pyspi python=3.9.0
+   $ conda activate pyspi
+
+
+Installation
+------------
+
+Next, download or clone the `latest version <https://github.com/olivercliff/pyspi>`_ from GitHub, unpack and install:
+
+.. code-block:: console
+
+   $ git clone https://github.com/olivercliff/pyspi.git 
+   $ cd pyspi
+   $ pip install .
+
+You can confirm that `pyspi` and dependencies installed properly with the following command:
+
+.. code-block:: console
+
+   $ setup.py test
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
@@ -1,36 +1,6 @@
 Usage
 =====
 
-Pre-installation
-----------------
-
-The code requires GNU's `Octave <https://www.gnu.org/software/octave/index>`_ by default, which is freely available on all popular operating systems.
-See the `installation instructions <https://wiki.octave.org/Category:Installation>`_ to find out how to install Octave on your system.
-
-.. note::
-   You can safely install `PySPI` without first installing Octave but you will not have access to the `Integrated Information Theory` statistics, see :ref:`Using the toolkit without Octave`.
-
-While you can also install `PySPI` outside of a `conda <https://docs.conda.io/projects/conda/en/latest/index.html>`_ environment, it depends on a lot of user packages that may make managing dependencies quite difficult.
-So, we would also recommend installing `PySPI` in a conda environment.
-After `installing conda <https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html>`_, create a new environment for using the toolkit:
-
-.. code-block:: console
-
-   $ conda create -n pyspi python=3.9.0
-   $ conda activate pyspi
-
-
-Installation
-------------
-
-Next, download or clone the `latest version <https://github.com/olivercliff/pyspi>`_ from GitHub, unpack and install:
-
-.. code-block:: console
-
-   $ git clone https://github.com/olivercliff/pyspi.git 
-   $ cd pyspi
-   $ pip install .
-
 
 Getting Started
 ---------------