Merge pull request #276 from astronomy-commons/restructuring-docs-tree

Restructure docs tree
astronomy-commons · Apr 11, 2024 · 4ae2c28 · 4ae2c28
2 parents 524f793 + 6f60afa
commit 4ae2c28
Show file tree

Hide file tree

Showing 16 changed files with 51 additions and 31 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -130,7 +130,7 @@ repos:
             "-d", # Flag for cached environment and doctrees
             "./docs/_build/doctrees", # Directory
             "-D", # Flag to override settings in conf.py
-            "exclude_patterns=notebooks/*", # Exclude our notebooks from pre-commit
+            "exclude_patterns=tutorials/*", # Exclude our notebooks from pre-commit
           ]
     # Run unit tests, verify that they pass. Note that coverage is run against
     # the ./src directory here because that is what will be committed. In the

diff --git a/README.md b/README.md
@@ -33,7 +33,7 @@ See related projects:
 
 [![GitHub issue custom search in repo](https://img.shields.io/github/issues-search/astronomy-commons/lsdb?color=purple&label=Good%20first%20issues&query=is%3Aopen%20label%3A%22good%20first%20issue%22)](https://github.com/astronomy-commons/lsdb/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
 
-See the [contribution guide](https://lsdb.readthedocs.io/en/stable/gettingstarted/contributing.html)
+See the [contribution guide](https://lsdb.readthedocs.io/en/stable/developer/contributing.html)
 for complete installation instructions and contribution best practices.
 
 ## Acknowledgements

diff --git a/docs/Makefile b/docs/Makefile
@@ -4,7 +4,7 @@
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?= -T -E -d _build/doctrees -D language=en
-EXCLUDENB     ?= -D exclude_patterns="notebooks/*","_build","**.ipynb_checkpoints"
+EXCLUDENB     ?= -D exclude_patterns="tutorials/*","_build","**.ipynb_checkpoints"
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = ../_readthedocs/

diff --git a/docs/_static/gaia.png b/docs/_static/gaia.png
diff --git a/docs/contact.rst b/docs/contact.rst
@@ -0,0 +1,12 @@
+Contact us
+===============================================================================
+
+We at LINCC Frameworks pride ourselves on being a friendly bunch!
+
+If you're encountering issues, have some gnarly dataset, have ideas for
+making our products better, or pretty much anything else, reach out!
+
+* Open an issue in our github repo for lsdb
+    * https://github.com/astronomy-commons/lsdb/issues/new
+* If you're on LSSTC slack, so are we!
+  `#lincc-frameworks-qa <https://lsstc.slack.com/archives/C062LG1AK1S>`_
diff --git a/docs/gettingstarted/contributing.rst → docs/developer/contributing.rst b/docs/gettingstarted/contributing.rst → docs/developer/contributing.rst
diff --git a/docs/gettingstarted.rst b/docs/gettingstarted.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -13,20 +13,38 @@ Built on top of Dask to efficiently scale and parallelize operations across mult
 the `HiPSCat <https://hipscat.readthedocs.io/en/stable/>`_ data format for surveys in a partitioned HEALPix
 (Hierarchical Equal Area isoLatitude Pixelization) structure.
 
+.. figure:: _static/gaia.png
+   :class: no-scaled-link
+   :scale: 80 %
+   :align: center
+   :alt: A possible HEALPix distribution for Gaia DR3
+
+   A possible HEALPix distribution for Gaia DR3.
+
 In this website you will find:
 
-- :doc:`Getting Started <gettingstarted>` guides on how to install and run an example workflow
-- :doc:`Tutorials <tutorials>`, and :doc:`Notebooks <notebooks>` with more advanced usage examples
+- Getting Started guides on how to :doc:`install <installation>` and run an :doc:`example workflow <tutorials/quickstart>`
+- :doc:`Tutorials <tutorials>` with more advanced usage examples
 - The detailed :doc:`API Reference <autoapi/index>` documentation
 
-Learn more about contributing to this repository in our :doc:`Contribution Guide <gettingstarted/contributing>`.
+Learn more about contributing to this repository in our :doc:`Contribution Guide <developer/contributing>`.
 
 .. toctree::
    :hidden:
 
    Home page <self>
-   Getting Started <gettingstarted>
+   Installation <installation>
+   Getting Started <tutorials/quickstart>
    Tutorials <tutorials>
-   Notebooks <notebooks>
+
+.. toctree::
+   :hidden:
+   :caption: Developer
+
    API Reference <autoapi/index>
+   Contribution Guide <developer/contributing>
+
+.. toctree::
+   :hidden:
 
+   Contact us <contact>
diff --git a/docs/gettingstarted/installation.rst → docs/installation.rst b/docs/gettingstarted/installation.rst → docs/installation.rst
diff --git a/docs/notebooks.rst b/docs/notebooks.rst
diff --git a/docs/notebooks/README.md b/docs/notebooks/README.md
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
@@ -4,9 +4,21 @@ Tutorials
 These pages contain a set of tutorial notebooks for working through core and more advanced LSDB
 functionality.
 
+Core functionality
+------------------
 .. toctree::
+    :maxdepth: 1
 
     Loading data into LSDB <tutorials/loading_data>
     Working with large catalogs <tutorials/working_with_large_catalogs>
     Margins <tutorials/margins>
-    Exporting results <tutorials/exporting_results>
+    Exporting results <tutorials/exporting_results>
+
+Other tutorials
+---------------
+.. toctree::
+    :maxdepth: 1
+
+    Import catalogs <tutorials/import_catalogs>
+    Cross-match ZTF BTS and NGC <tutorials/ztf_bts-ngc>
+    Import and cross-match DES and Gaia <tutorials/des-gaia>
diff --git a/docs/notebooks/des-gaia.ipynb → docs/tutorials/des-gaia.ipynb b/docs/notebooks/des-gaia.ipynb → docs/tutorials/des-gaia.ipynb
diff --git a/docs/notebooks/import_catalogs.ipynb → docs/tutorials/import_catalogs.ipynb b/docs/notebooks/import_catalogs.ipynb → docs/tutorials/import_catalogs.ipynb
diff --git a/docs/gettingstarted/quickstart.ipynb → docs/tutorials/quickstart.ipynb b/docs/gettingstarted/quickstart.ipynb → docs/tutorials/quickstart.ipynb
diff --git a/docs/notebooks/ztf_bts-ngc.ipynb → docs/tutorials/ztf_bts-ngc.ipynb b/docs/notebooks/ztf_bts-ngc.ipynb → docs/tutorials/ztf_bts-ngc.ipynb