docs: reorganise the doc + API docs + logo

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>`_

docs/api.md

@@ -0,0 +1,46 @@
+# API reference
+
+These pages contain the API reference for the `jaxoplanet` package.
+
+```{warning}
+While being stable, the rest of the API is still subject to change. This is particularly true for the `experimental.starry` module.
+```
+
+## Orbital systems
+
+The modules to define orbital systems are:
+
+- [keplerian](jaxoplanet.orbits.keplerian) : a module to define systems 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.
+- [starry](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)
+
+## Light curves
+
+Given an orbital system, the following modules can be used to compute different kind of light-curves light curves:
+
+- [limb-darkened](jaxoplanet.light_curves.limb_dark) : a module to compute occultation light curve of a star with polynomial limb darkening.
+- [starry](jaxoplanet.experimental.starry.surface) : a module to compute the light curve of a non-uniform star whose surface is represented by a sum of spherical harmonics.
+
+## Surface maps
+
+The following module can be used to create and manipulate non-uniform surface maps:
+
+- [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.ylm) : 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>
+starry light curve <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).

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"

docs/index.md

@@ -4,11 +4,29 @@
 ## Table of contents
 
 ```{toctree}
----
-maxdepth: 1
----
+:caption: User guide
 
-guide
-tutorials
+why
+install
+troubleshooting
+tutorials/getting-started.ipynb
+```
+
+```{toctree}
+:caption: Tutorials
+
+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
+
 ```

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