Major update to docs (#143)

* More docstrings

* More docs updates

* More docs updates

* API link

* Update RV tutorial

Author: dfm

CONTRIBUTING.md

@@ -1,19 +1,43 @@
-## Contributing to exoplanet-jax
+# Contributor Guide
 
-### Reporting issues
+Thank you for your interest in improving this project. This project is
+open-source and welcomes contributions in the form of bug reports, feature
+requests, and pull requests.
 
-If you find a bug or other unexpected behavior while using `exoplanet-jax`,
-open an issue on the [GitHub repository](https://github.com/exoplanet-dev/exoplanet-jax/issues)
-and we will try to respond and (hopefully) solve the problem in a timely manner.
-Similarly, if you have a feature request or question about the library, the best
-place to post those is currently on GitHub as an issue, but that is likely
-change if the user community grows. If you report an issue, please give the
-details needed to reproduce the problem (version of exoplanet, its dependencies,
-and your platform) and a small standalone piece of code that demonstrates the
-problem clearly.
+Here is a list of important resources for contributors:
 
-### Contributing code
+- [Source Code](https://github.com/exoplanet-dev/jaxoplanet)
+- [Documentation](https://jax.exoplanet.codes)
+- [Issue Tracker](https://github.com/exoplanet-dev/jaxoplanet/issues)
 
-We welcome contributions to the codebase of all scales from typo fixes to new features,
-but if you would like to add a substantial feature, it would be a good idea to first
-open an issue that describes your plan so that we can discuss in advance.
+## How to report a bug
+
+Report bugs on the [Issue Tracker](https://github.com/exoplanet-dev/jaxoplanet/issues).
+
+When filing an issue, make sure to answer these questions:
+
+- Which operating system and Python version are you using?
+- Which version of this project are you using?
+- What did you do?
+- What did you expect to see?
+- What did you see instead?
+
+The best way to get your bug fixed is to provide a test case, and/or steps to
+reproduce the issue. In particular, please include a [Minimal, Reproducible
+Example](https://stackoverflow.com/help/minimal-reproducible-example).
+
+## How to request a feature
+
+Feel free to request features on the [Issue
+Tracker](https://github.com/exoplanet-dev/jaxoplanet/issues).
+
+## How to test the project
+
+```bash
+python -m pip install nox
+python -m nox -s test
+```
+
+## How to submit changes
+
+Open a [Pull Request](https://github.com/exoplanet-dev/jaxoplanet/pulls).

README.md

@@ -4,18 +4,23 @@ _Astronomical time series analysis with JAX_
 
 ---
 
-_jaxoplanet_ is a [functional-programming](https://en.wikipedia.org/wiki/Functional_programming)-forward implementation of many features from the
+_jaxoplanet_ is a
+[functional-programming](https://en.wikipedia.org/wiki/Functional_programming)-forward
+implementation of many features from the
 [exoplanet](https://docs.exoplanet.codes/en/latest/) and
 [starry](https://starry.readthedocs.io/en/latest/) packages built on top of
 [JAX](https://jax.readthedocs.io/en/latest/).
 
 *jaxoplanet* includes fast and robust implementations of many exoplanet-specific
 operations, including solving Kepler's equation, and computing limb-darkened
-light curves. Since *jaxoplanet* is built on top of JAX it has have first-class
-support for hardware acceleration using GPUs and TPUs, and it also integrates seamlessly
-with modeling tools like [NumPyro](https://numpyro.readthedocs.io/en/latest/),
-and [Flax](https://flax.readthedocs.io/en/latest/).
+light curves. Since *jaxoplanet* is built on top of JAX it has first-class
+support for hardware acceleration using GPUs and TPUs, and it also integrates
+seamlessly with modeling tools like
+[NumPyro](https://numpyro.readthedocs.io/en/latest/), and
+[Flax](https://flax.readthedocs.io/en/latest/).
 
+**For the most complete documentation, check out the documentation page at
+[jax.exoplanet.codes](https://jax.exoplanet.codes).**
 
 ## Installation
 
@@ -33,14 +38,17 @@ Then install _jaxoplanet_ with:
 python -m pip install jaxoplanet
 ```
 
-If you run into issues with installing *jaxoplanet*, take a look at the **Troubleshooting on *jaxoplanet* installation** page.
+If you run into issues with installing *jaxoplanet*, take a look at [the
+installation instructions](https://jax.exoplanet.codes/en/latest/install).
 
 ## Quick start
 
 
 ## Attribution
-While we don't yet have a citation for *jaxoplanet*, please reference the GitHub repository if you find
-this code useful in your research. The BibTeX entry for the repo is:
+
+While we don't yet have a citation for *jaxoplanet*, please reference the GitHub
+repository if you find this code useful in your research. The BibTeX entry for
+the repo is:
 
 ```
 @software{jaxoplanet,
@@ -56,4 +64,5 @@ this code useful in your research. The BibTeX entry for the repo is:
 ## License
 Copyright (c) 2021-2024 Simons Foundation, Inc.
 
-*jaxoplanet* is free software made available under the MIT License. For details see the LICENSE file.
+*jaxoplanet* is free software made available under the MIT License. For details
+see the LICENSE file.

docs/code-of-conduct.md

@@ -0,0 +1,3 @@
+```{include} ../CODE_OF_CONDUCT.md
+
+```

docs/contributing.md

@@ -0,0 +1,12 @@
+(contributing)=
+
+```{include} ../CONTRIBUTING.md
+
+```
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+code-of-conduct
+```

docs/guide.md

@@ -0,0 +1,15 @@
+(guide)=
+
+# User Guide
+
+The following pages give some background on the context within which `jaxoplanet`
+exists, as well as detailed installation and API documentation. Click through
+for all the details, or head over to the {ref}`tutorials` for a more hands-on
+experience.
+
+```{toctree}
+:maxdepth: 1
+
+install
+troubleshooting
+```

docs/index.md

@@ -8,6 +8,7 @@
 maxdepth: 1
 ---
 
-installation
+guide
 tutorials
+contributing
 ```

docs/install.md

@@ -0,0 +1,39 @@
+(install)=
+
+# Installation Guide
+
+`jaxoplanet` is built on top of [`jax`](https://github.com/google/jax) so that's the
+primary dependency that you'll need. All of the methods below will install any
+required dependencies, but if you want to take advantage of your GPU, that might
+take a little more setup. `jaxoplanet` doesn't have any GPU-specific code, so it
+should be enough to just [follow the installation instructions for CUDA support
+in the `jax` README](https://github.com/google/jax/#installation).
+
+## Using pip
+
+The easiest way to install the most recent stable version of `jaxoplanet` is
+with [pip](https://pip.pypa.io):
+
+```bash
+python -m pip install jaxoplanet
+```
+
+## From source
+
+Alternatively, you can get the source:
+
+```bash
+git clone https://github.com/exoplanet-dev/jaxoplanet.git
+cd jaxoplanet
+python -m pip install -e .
+```
+
+## Tests
+
+If you installed from source, you can run the unit tests. From the root of the
+source directory, run:
+
+```bash
+python -m pip install nox
+python -m nox -s test
+```

docs/installation.md

@@ -0,0 +1,80 @@
+(troubleshooting)=
+
+# Troubleshooting
+
+This page includes some tips for troubleshooting issues that you might run into
+when using `jaxoplanet`. This is a work-in-progress, so if you don't see your
+issue listed here, feel free to open an issue on the [GitHub repository issue
+tracker](https://github.com/exoplanet-dev/jaxoplanet/issues).
+
+## NaNs and infinities
+
+It's not that uncommon to hit NaNs or infinities when using `jax` and
+`jaxoplanet`. This is often caused by numerical precision issues, and this can
+be exacerbated by the fact that, by default, `jax` disables double precision
+calculations. You can enable double precision [a few different ways as described
+in the `jax`
+docs](https://jax.readthedocs.io/en/latest/notebooks/Common_Gotchas_in_JAX.html#double-64bit-precision),
+and the way we do it in these docs is to add the following, when necessary:
+
+```python
+import jax
+
+jax.config.update("jax_enable_x64", True)
+```
+
+If enabling double precision doesn't do the trick, this often means that there's
+an issue with the parameter or modeling choices that you're making. `jax`'s
+["debug NaNs" mode](https://jax.readthedocs.io/en/latest/debugging/flags.html)
+can help diagnose issues here.
+
+## Installation issues on ARM Macs
+
+Follow these steps to install `jax` and `jaxoplanet` on your system, with
+special instructions for Mac M1 chip or newer.
+
+### Step 1: Check Your Python Architecture
+
+First, verify your Python architecture to determine if you're on an ARM or
+Intel-based chip.
+
+```bash
+import platform
+platform.machine()
+```
+
+- If the output is "arm64", proceed with the following steps.
+- If the output is "x86-64", you're running an Intel emulator on an Apple
+  silicon chip and need to switch to arm64.
+
+For the best performance of `jax`, it will be better to install Python under
+the arm64 architecture.
+
+**Install Miniforge for ARM64.**
+
+Download Miniforge from the official Conda Forge page (https://conda-forge.org/miniforge/).
+Run the installer script:
+
+```bash
+bash Mambaforge-23.11.0-0-MacOSX-arm64.sh
+```
+
+Restart the terminal.
+
+### Step 2: Install `jax` and `jaxoplanet`
+
+Create a New Environment (Optional) in miniforge.
+
+It's a good practice to create a new environment for your projects:
+
+```bash
+conda create --name jaxoplanet
+conda activate jaxoplanet
+conda install pip
+
+conda install jax
+# or
+python -m pip install "jax[cpu]"
+```
+
+Then install `jaxoplanet` using the instructions in {ref}`install`.