docs: reorganise the doc + API docs + logo (#191)

* docs: adding a clean API page (keep autoapi?) + open toctree * docs: more docstrings * docs: revamped tutorial to include more measurements (RV ,light curve, starry todo) * docs: removed unused * docs: fix main docstrings * docs: adding a logo * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix: line too long * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * docs: adding full api link * docs: fix objects refs * docs: temporary remove fail on warning * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * docs: make autoapi index orphan (to avoid warnings in sphinx) + fix rst list format (sphinx warning) * docs: separate starry api * docs: remove why.md * fix: map_light_curve dosctring * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * docs: reset `sphinx -W` option to fail on warning * docs: add about page to tutorials + modify transit tuto to reflect that * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * fix: api ref * docs: add link to about * docs: put model_light_curve into function * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * docs: remove duplicate note about extra packages * fix: add @jiayindong suggestions and `light_curves.transforms` to API --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
exoplanet-dev · Aug 8, 2024 · bf25afa · bf25afa
1 parent 7a0ba3c
commit bf25afa
Show file tree

Hide file tree

Showing 19 changed files with 502 additions and 208 deletions.
diff --git a/docs/_autoapi_templates/index.rst b/docs/_autoapi_templates/index.rst
@@ -0,0 +1,15 @@
+:orphan:
+
+Full API Reference
+==================
+
+This page contains auto-generated API reference documentation [#f1]_.
+
+.. toctree::
+   :titlesonly:
+
+   {% for page in pages|selectattr("is_top_level_object") %}
+   {{ page.include_path }}
+   {% endfor %}
+
+.. [#f1] Created with `sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi>`_
diff --git a/docs/_static/favicon.png b/docs/_static/favicon.png
diff --git a/docs/_static/logo.png b/docs/_static/logo.png
diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,55 @@
+# API reference
+
+These pages contain the API reference for the `jaxoplanet` package.
+
+## Orbital systems
+
+The modules to define orbital systems are:
+
+- [keplerian](jaxoplanet.orbits.keplerian) : a module to define a Keplerian system made of a central object and its orbiting bodies.
+- [transit](jaxoplanet.orbits.transit) : a module to define a system made of a star and its transiting planet, defined by the transit parameters assuming the planet transits at a constant velocity.
+
+## Limb-darkened stars
+
+Given an orbital system, the following modules can be used to compute different kind of light curves:
+
+- [limb-darkened](jaxoplanet.light_curves.limb_dark) : a module to compute occultation light curve of a star with polynomial limb darkening.
+- [transforms](jaxoplanet.light_curves.transforms) : a module providing decorators to transform light curve functions.
+
+
+## Non-uniform surfaces
+
+
+```{warning}
+While being stable, computing *starry* light curves of non-uniform surfaces is still experimental.
+```
+
+The following modules can be used to create systems of bodies with limb-darkened and non-uniform emitting surfaces:
+
+- [starry orbit](jaxoplanet.experimental.starry.orbit) : a module to define a system made of a central object and orbiting bodies, all with non-uniform emitting surfaces. (experimental)
+- [starry light curve](jaxoplanet.experimental.starry.light_curves) : a module to compute the light curve of a non-uniform star whose surface is represented by a sum of spherical harmonics.
+
+And the following are lower-level modules to define and manipulate non-uniform surfaces:
+
+- [Ylm](jaxoplanet.experimental.starry.ylm) : a lower-level module to create and manipulate vectors in the spherical harmonic basis.
+- [Pijk](jaxoplanet.experimental.starry.pijk) : a lower-level module to create and manipulate vectors in the polynomial basis.
+- [Surface](jaxoplanet.experimental.starry.surface) : a module to manipulate the oriented surface of spherical bodies, represented by a sum of spherical harmonics.
+- [visualization](jaxoplanet.experimental.starry.visualization) : a module to visualize the surface of non-uniform spherical bodies.
+
+
+```{toctree}
+:hidden:
+
+keplerian orbit <autoapi/jaxoplanet/orbits/keplerian/index>
+transit orbit <autoapi/jaxoplanet/orbits/transit/index>
+starry orbit <autoapi/jaxoplanet/experimental/starry/orbit/index>
+limb-darkened light curve <autoapi/jaxoplanet/light_curves/limb_dark/index>
+transforms <autoapi/jaxoplanet/light_curves/transforms/index>
+starry light curve <autoapi/jaxoplanet/experimental/starry/light_curves/index>
+Surface <autoapi/jaxoplanet/experimental/starry/surface/index>
+Ylm <autoapi/jaxoplanet/experimental/starry/ylm/index>
+Pijk <autoapi/jaxoplanet/experimental/starry/pijk/index>
+visualization <autoapi/jaxoplanet/experimental/starry/visualization/index>
+```
+
+**Missing something?** Check the [full API reference](autoapi/jaxoplanet/index).
diff --git a/docs/conf.py b/docs/conf.py
@@ -19,7 +19,7 @@
 ]
 
 autoapi_dirs = ["../src"]
-autoapi_ignore = ["*/experimental/*", "*_version*", "*/types*"]
+autoapi_ignore = ["*_version*", "*/types*"]
 autoapi_options = [
     "members",
     "undoc-members",
@@ -29,6 +29,9 @@
     "special-members",
     # "imported-members",
 ]
+# autoapi_add_toctree_entry = False
+autoapi_template_dir = "_autoapi_templates"
+
 suppress_warnings = ["autoapi.python_import_resolution"]
 
 myst_enable_extensions = ["dollarmath", "colon_fence"]
@@ -44,7 +47,7 @@
 version = jaxoplanet.__version__
 release = jaxoplanet.__version__
 
-exclude_patterns = ["_build"]
+exclude_patterns = ["_build", "_autoapi_templates"]
 html_theme = "sphinx_book_theme"
 html_title = "jaxoplanet documentation"
 html_logo = "_static/logo.png"

diff --git a/docs/guide.md b/docs/guide.md
diff --git a/docs/index.md b/docs/index.md
@@ -4,11 +4,29 @@
 ## Table of contents
 
 ```{toctree}
----
-maxdepth: 1
----
+:caption: User guide
 
-guide
-tutorials
+install
+troubleshooting
+tutorials/getting-started.ipynb
+```
+
+```{toctree}
+:caption: Tutorials
+
+tutorials/about.ipynb
+tutorials/transit.ipynb
+tutorials/rv.ipynb
+tutorials/starry.ipynb
+```
+
+```{toctree}
+:caption: Reference
+
+api
+tutorials/autodiff.ipynb
+tutorials/introduction-to-jax.ipynb
+tutorials/core-from-scratch.ipynb
 contributing
+
 ```
diff --git a/docs/install.md b/docs/install.md
@@ -1,6 +1,6 @@
 (install)=
 
-# Installation Guide
+# Installation
 
 `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

diff --git a/docs/tutorials.md b/docs/tutorials.md
diff --git a/docs/tutorials/about.ipynb b/docs/tutorials/about.ipynb
@@ -0,0 +1,79 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# About these tutorials\n",
+    "\n",
+    "The tutorials in this section are automatically executed with every change of\n",
+    "the code to make sure that they are always up-to-date. As a result, they are\n",
+    "designed to require only a relatively small amount of computation time; when\n",
+    "using `jaxoplanet` for real problems you will probably find that your run\n",
+    "times are longer.\n",
+    "\n",
+    "To execute a tutorial on your own, you can click on the buttons at the top right\n",
+    "or this page to launch the notebook using [Binder](https://mybinder.org),\n",
+    "[Colab](https://colab.research.google.com), or download the `.ipynb` file\n",
+    "directly.\n",
+    "\n",
+    "## Extra dependencies\n",
+    "\n",
+    "Most of these tutorials use the probabilistic programming library `NumPyro` to make \n",
+    "inference based on real or synthetic datasets. Hence, you will need the following extra packages:\n",
+    "- [NumPyro](https://num.pyro.ai/en/stable/getting_started.html) : a lightweight probabilistic programming library.\n",
+    "- [NumPyro-ext](https://github.com/dfm/numpyro-ext) : a package that extends NumPyro with a set of helper functions, custom distributions and other utilities.\n",
+    "- [corner](https://corner.readthedocs.io/en/latest/) : a package to visualize multidimensional samples using a scatterplot matrix.\n",
+    "- [Arviz](https://python.arviz.org/en/stable/) : a package for exploratory analysis of Bayesian models\n",
+    "\n",
+    "In addition, the [Lightkurve](https://docs.lightkurve.org/) may be required to download real datasets from the Kepler and TESS missions.\n",
+    "\n",
+    "For reference, here is the version of the packages used to generate these tutorials:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import jax\n",
+    "import arviz\n",
+    "import numpy\n",
+    "import corner\n",
+    "import numpyro\n",
+    "import jaxoplanet\n",
+    "import numpyro_ext\n",
+    "\n",
+    "print(f\"jaxoplanet.__version__ = {jaxoplanet.__version__}\")\n",
+    "print(f\"numpy.__version__ = {numpy.__version__}\")\n",
+    "print(f\"numpyro.__version__ = {numpyro.__version__}\")\n",
+    "print(f\"numpyro_ext.__version__ = {numpyro_ext.__version__}\")\n",
+    "print(f\"jax.__version__ = {jax.__version__}\")\n",
+    "print(f\"corner.__version__ = {corner.__version__}\")\n",
+    "print(f\"arviz.__version__ = {arviz.__version__}\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "jaxoplanet",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}