Update docs homepage (#44)

kyleaoman · web-flow · commit 4953eee409eb · 2025-06-08T13:28:06.000+01:00
* Simplify docs homepage and relocate some information.
diff --git a/README.rst b/README.rst
@@ -30,7 +30,20 @@ SWIFTGalaxy
 
 SWIFTGalaxy is a module that extends SWIFTSimIO_ tailored to analyses of particles belonging to individual simulated galaxies. It inherits from and extends the functionality of the ``SWIFTDataset``. It understands the content of halo catalogues (supported: `Velociraptor`_, `Caesar`_, `SOAP`_) and therefore which particles belong to a galaxy or other group of particles, and its integrated properties. The particles occupy a coordinate frame that is enforced to be consistent, such that particles loaded on-the-fly will match e.g. rotations and translations of particles already in memory. Intuitive masking of particle datasets is also enabled. Utilities to make working in cylindrical and spherical coordinate systems more convenient are also provided. Finally, tools to iterate efficiently over multiple galaxies are also provided.
 
-Installation is as simple as ``pip install swiftgalaxy``. Once installed, creating a ``SWIFTGalaxy`` object to get started with analysis is simple! For example, for a SWIFT simulation with a SOAP-format halo catalogue (an example - 300 MB - will be automatically downloaded):
+.. _SWIFTSimIO: http://swiftsimio.readthedocs.org
+.. _Velociraptor: https://ui.adsabs.harvard.edu/abs/2019PASA...36...21E/abstract
+.. _Caesar: https://caesar.readthedocs.io/en/latest/
+.. _SOAP: https://github.com/SWIFTSIM/SOAP
+
+.. INTRO_END_LABEL
+
+Installation_ is as simple as ``pip install swiftgalaxy``. Dependencies for using SOAP, Caesar and Velociraptor catalogues can be installed with ``pip install swiftgalaxy[soap,caesar,velociraptor]``.
+
+.. _Installation: https://swiftgalaxy.readthedocs.io/en/latest/getting_started/index.html#installing
+
+.. EXAMPLE_START_LABEL
+
+Once installed, creating a ``SWIFTGalaxy`` object to get started with analysis is simple! For example, for a SWIFT simulation with a SOAP-format halo catalogue (an example - 300 MB - will be automatically downloaded):
 
 .. code-block:: python
 
@@ -45,6 +58,9 @@ Installation is as simple as ``pip install swiftgalaxy``. Once installed, creati
    # access data for particles belonging to the galaxy:
    sg.gas.temperatures
 
+   # access integrated properties from the halo catalogue
+   sg.halo_catalogue.spherical_overdensity_200_crit.soradius
+
    # automatically generated spherical/cylindrical coordinates:
    sg.gas.spherical_coordinates.r
 
@@ -74,13 +90,7 @@ Installation is as simple as ``pip install swiftgalaxy``. Once installed, creati
 
 .. image:: eagle6_galaxy.png
 
-.. _SWIFTSimIO: http://swiftsimio.readthedocs.org
-.. _Velociraptor: https://ui.adsabs.harvard.edu/abs/2019PASA...36...21E/abstract
-.. _Caesar: https://caesar.readthedocs.io/en/latest/
-.. _SOAP: https://github.com/SWIFTSIM/SOAP
-.. _PyPI: https://pypi.org
-
-.. INTRO_END_LABEL
+.. EXAMPLE_END_LABEL
 
 Examples
 --------
@@ -140,6 +150,8 @@ Please also consider the `citations requested for SWIFTSimIO <citeSWIFTSimIO>`_.
 Community
 ---------
 
+.. COMMUNITY_START_LABEL
+
 Code contributions are very welcome! A good place to start is the `contributing guide`_ and how to set up a `development environment`_.
 
 SWIFTGalaxy is licensed under `GPL-3.0`_ and community members are expected to abide by the `code of conduct`_.
@@ -148,3 +160,5 @@ SWIFTGalaxy is licensed under `GPL-3.0`_ and community members are expected to a
 .. _development environment: https://swiftgalaxy.readthedocs.io/en/latest/getting_started/index.html#installing
 .. _GPL-3.0: https://github.com/SWIFTSIM/swiftgalaxy/tree/main?tab=GPL-3.0-1-ov-file
 .. _code of conduct: https://github.com/SWIFTSIM/swiftgalaxy/tree/main?tab=coc-ov-file
+
+.. COMMUNITY_END_LABEL
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,5 +1,6 @@
 sphinx
 sphinx-rtd-theme
+sphinx-design
 recommonmark
 numpy
 numba
diff --git a/docs/source/citing/index.rst b/docs/source/citing/index.rst
@@ -0,0 +1,6 @@
+Citing SWIFTGalaxy
+==================
+
+.. include:: ../../../README.rst
+   :start-after: CITING_START_LABEL
+   :end-before: CITING_END_LABEL
diff --git a/docs/source/community/index.rst b/docs/source/community/index.rst
@@ -0,0 +1,6 @@
+Developer guide
+===============
+
+.. include:: ../../../README.rst
+   :start-after: COMMUNITY_START_LABEL
+   :end-before: COMMUNITY_END_LABEL
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -41,6 +41,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
+    "sphinx_design",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/docs/source/getting_started/eagle6_galaxy.png b/docs/source/getting_started/eagle6_galaxy.png
diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst
@@ -113,33 +113,18 @@ and `pre-push hook`_:
 .. _pre-commit hook: https://git-scm.com/book/ms/v2/Customizing-Git-Git-Hooks
 .. _pre-push hook: https://git-scm.com/book/ms/v2/Customizing-Git-Git-Hooks
 
+.. _quick-start:
 
 Quick start
 -----------
 
-:mod:`swiftgalaxy` comes with some tools to procedurally generate very simple example data, and to download more realistic example data (~300 MB). Using the genrated example snapshot :file:`toysnap_virtual.hdf5` and SOAP catalogue :file:`toysoap.hdf5`, initializing a :class:`SWIFTGalaxy` for the galaxy in the first row (indexed from 0) in the SOAP catalogue is as easy as:
+.. include:: ../../../README.rst
+   :start-after: EXAMPLE_START_LABEL
+   :end-before: EXAMPLE_END_LABEL
 
-.. code-block:: python
-
-    from swiftgalaxy import SWIFTGalaxy, SOAP
-    from swiftgalaxy.demo_data import generated_examples
-
-    sg = SWIFTGalaxy(
-        generated_examples.virtual_snapshot,  # autofills the name of the snapshot "toysnap.hdf5"
-        SOAP(
-            generated_examples.soap,  # autofills the name of the catalogue "toysoap.hdf5"
-            soap_index=0
-        )
-    )
-
-Like a :class:`~swiftsimio.reader.SWIFTDataset`, the particle datasets are accessed as below, and all data are loaded 'lazily', on demand.
-
-.. code-block:: python
-
-    sg.gas.particle_ids
-    sg.dark_matter.coordinates
+Like a :class:`~swiftsimio.reader.SWIFTDataset`, all data are loaded 'lazily' on demand.
 
-However, information from the halo catalogue is used to select only the particles identified as bound to this galaxy. The coordinate system is centred in both position and velocity on the centre and peculiar velocity of the galaxy, as determined by the halo finder. The coordinate system can be further manipulated, and all particle arrays will stay in a consistent reference frame at all times.
+However, information from the halo catalogue is used to select only the particles identified as bound to this galaxy. The coordinate system is centred in both position and velocity on the centre and peculiar velocity of the galaxy, as determined by the halo catalogue. The coordinate system can be further manipulated, and all particle arrays will stay in a consistent reference frame at all times.
 
 Again like for a :class:`~swiftsimio.reader.SWIFTDataset`, the units and metadata information are available:
 
@@ -148,33 +133,6 @@ Again like for a :class:`~swiftsimio.reader.SWIFTDataset`, the units and metadat
     sg.units
     sg.metadata
 
-The halo catalogue interface is accessible as shown below. What this interface looks like depends on the halo finder being used, but will provide values for the individual galaxy of interest.
-
-.. code-block:: python
-
-    sg.halo_catalogue
-
-In this case with :class:`~swiftgalaxy.halo_catalogues.SOAP`, we can get the centre of mass of the bound particles like this:
-
-.. code-block:: python
-
-    sg.halo_catalogue.bound_subhalo.centre_of_mass
-
-The procedurally generated example conforms to the data format of a real data set, but quantitatively speaking the contents are mostly nonsensical, and the halo catalogue has many fewer fields than a "real" one. A more interesting example data set, a :math:`(6\,\mathrm{Mpc})^3` EAGLE simulation at z=?? (about 300 MB to download) can be initialized with:
-
-.. code-block:: python
-
-    from swiftgalaxy import SWIFTGalaxy, SOAP
-    from swiftgalaxy.demo_data import web_examples
-
-    sg = SWIFTGalaxy(
-        web_examples.virtual_snapshot,  # autofills the name of the snapshot "EagleSingleVirtual.hdf5"
-        SOAP(
-            web_examples.soap,  # autofills the name of the catalogue "SOAPEagleSingle.hdf5"
-            soap_index=0
-        )
-    )		
-
 :mod:`swiftgalaxy` supports Python's tab completion features. This means that you can browse the available attributes of objects in an interactive interpreter by starting to type an attribute (or just a trailing dot) and pressing tab twice. A few examples to help start exploring:
 
    - ``sg.<tab><tab>``
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,12 +1,81 @@
 SWIFTGalaxy
 ===========
 
-In a hurry? :doc:`Quick-start <getting_started/index>`.
-
 .. include:: ../../README.rst
    :start-after: INTRO_START_LABEL
    :end-before: INTRO_END_LABEL
 
+.. grid:: 1 2 1 2
+    :margin: 5 5 0 0
+    :padding: 0 0 0 0
+    :gutter: 4
+
+    .. grid-item-card:: :octicon:`info` Getting started
+        :text-align: center
+        :class-title: sd-fs-5
+        :class-card: sd-p-3
+
+        .. button-ref:: getting_started/index
+            :color: primary
+            :outline:
+            :expand:
+
+	    installation
+
+        .. button-ref:: quick-start
+            :color: primary
+            :outline:
+            :expand:
+
+	    quick start guide
+	    
+    .. grid-item-card:: :octicon:`code-square` Contributing
+        :text-align: center
+        :class-title: sd-fs-5
+        :class-card: sd-p-3
+
+        .. button-ref:: community/index
+            :click-parent:
+            :color: primary
+            :outline:
+            :expand:
+
+            information for developers
+
+	.. button-link:: https://github.com/SWIFTSIM/swiftgalaxy
+            :click-parent:
+            :color: primary
+            :outline:
+            :expand:
+
+            :octicon:`mark-github` source code :octicon:`link-external`
+
+    .. grid-item-card:: :octicon:`file-badge` Reference documentation
+        :text-align: center
+        :class-title: sd-fs-5
+        :class-card: sd-p-3
+
+        .. button-ref:: modules/index
+            :click-parent:
+            :color: primary
+            :outline:
+            :expand:
+
+	    lists of modules and functions
+
+    .. grid-item-card:: :octicon:`bookmark` Publishing?
+        :text-align: center
+        :class-title: sd-fs-5
+        :class-card: sd-p-3
+
+        .. button-ref:: citing/index
+	    :click-parent:
+            :color: primary
+            :outline:
+            :expand:
+
+	    citation information
+
 Documentation contents
 ----------------------
 	     
@@ -22,14 +91,10 @@ Documentation contents
    masking/index
    iterating/index
    visualisation/index
+   community/index
+   citing/index
    modules/index
 
-Citing SWIFTGalaxy
-------------------
-
-.. include:: ../../README.rst
-   :start-after: CITING_START_LABEL
-   :end-before: CITING_END_LABEL
 
 Indices and tables
 ------------------
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swiftgalaxy"
-version="2.0.3"
+version="2.1.0"
 authors = [
     { name="Kyle Oman", email="kyle.a.oman@durham.ac.uk" },
 ]

Original file line number	Diff line number	Diff line change
`@@ -41,6 +41,7 @@`
`41`	`41`	`"sphinx.ext.mathjax",`
`42`	`42`	`"sphinx.ext.autosummary",`
`43`	`43`	`"sphinx.ext.intersphinx",`
	`44`	`+ "sphinx_design",`
`44`	`45`	`]`
`45`	`46`
`46`	`47`	`# Add any paths that contain templates here, relative to this directory.`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"`
`4`	`4`
`5`	`5`	`[project]`
`6`	`6`	`name = "swiftgalaxy"`
`7`		`-version="2.0.3"`
	`7`	`+version="2.1.0"`
`8`	`8`	`authors = [`
`9`	`9`	`{ name="Kyle Oman", email="kyle.a.oman@durham.ac.uk" },`
`10`	`10`	`]`