Update docs theme and citation page

docs/citation.rst

@@ -1,37 +1,45 @@
 Papers & Citation
 =================
 
-Citation
---------
-.. TODO: are we asking users to cite all of these papers? Let's be clear.
-
-Use of AbacusSummit should cite `Maksimova et al. (2021) <https://academic.oup.com/mnras/article/508/3/4017/6366248>`_ for the
-simulation suite; `Garrison et al. (2021) <https://academic.oup.com/mnras/article/508/1/575/6366254>`_, `Garrison et al. (2019) <https://academic.oup.com/mnras/article/485/3/3370/5371170>`_,
-and `Garrison et al. (2018) <https://iopscience.iop.org/article/10.3847/1538-4365/aabfd3>`_ for the Abacus code;
-and `Metchnik (2009) <https://ui.adsabs.harvard.edu/abs/2009PhDT.......175M/abstract>`_
-for the initial method.  
-Applications using the CompaSO halos should cite `Hadzhiyska et al. (2021) <https://academic.oup.com/mnras/advance-article/doi/10.1093/mnras/stab2980/6402914>`_ for that method; those using the AbacusSummit halo light cone catalogues should cite `Hadzhiyska et al. (2021) <https://academic.oup.com/mnras/advance-article/doi/10.1093/mnras/stab3066/6408495>`_; and those using the AbacusSummit halo merger trees should cite `Bose et al. <https://arxiv.org/abs/2110.11409>`_
-Other citations may be requested as we publish more of the numerical methods.
-
-We provide a BibTeX file with these references `here <https://github.com/abacusorg/AbacusSummit/blob/master/papers.bib>`_.
-
-.. _papers:
-
-Papers
--------
-AbacusSummit is described in `Maksimova et al. (2021, MNRAS, 508, 4017) <https://academic.oup.com/mnras/article/508/3/4017/6366248>`_. 
-The Abacus N-body code is described in  `Garrison et al. (2021, MNRAS, 508, 575) <https://academic.oup.com/mnras/article/508/1/575/6366254>`_ and `Garrison et al. (2019, MNRAS, 485, 3370) <https://academic.oup.com/mnras/article/485/3/3370/5371170>`_,
-where we detail its performance on the `Schneider et al. (2016, JCAP) <https://iopscience.iop.org/article/10.1088/1475-7516/2016/04/047>`_ code
-comparison simulation, and in `Garrison et al. (2018, ApJS, 236,
-43) <https://iopscience.iop.org/article/10.3847/1538-4365/aabfd3>`_,
-which released an early suite of 125 simulations from 40
-cosmologies (https://lgarrison.github.io/AbacusCosmos/).
-
-`Garrison et al. (2016, MNRAS, 461, 4125) <https://academic.oup.com/mnras/article/461/4/4125/2608725>`_ describes
-our initial condition methods. `Hadzhiyska et al. (2021, MNRAS) <https://academic.oup.com/mnras/advance-article/doi/10.1093/mnras/stab2980/6402914>`_ 
-describes the CompaSO group finding method. `Hadzhiyska et al. (2021, MNRAS) <https://academic.oup.com/mnras/advance-article/doi/10.1093/mnras/stab3066/6408495>`_ documents the method for generating light cones on the fly in AbacusSummit; `Bose et al. <https://arxiv.org/abs/2110.11409>`_ describes the procedure for generating high-fidelity halo merger trees from AbacusSummit. The AbacusHOD model is presented in `Yuan  et al. <https://arxiv.org/abs/2110.11412>`_
-
-Pinto et al. (in prep) will
-describe the Abacus far-field method.  Using scale-free simulations, `Joyce et al. (2021, MNRAS, 501, 5051) <https://academic.oup.com/mnras/article/501/4/5051/5979795>`_
-describes accuracy tests, and `Garrison et al. (2021, MNRAS, 504, 3550) <https://academic.oup.com/mnras/article/504/3/3550/6246417>`_
-validates the force softening scheme.
+.. sidebar:: BibTeX References
+
+    .. tip::
+        We provide a BibTeX file with the references on this page `here <https://github.com/abacusorg/AbacusSummit/blob/master/papers.bib>`__.
+
+Use of AbacusSummit should cite at least the following two papers:
+
+* *AbacusSummit: a massive set of high-accuracy, high-resolution N-body simulations*, `Maksimova et al. (2021) <https://academic.oup.com/mnras/article/508/3/4017/6366248>`__ (describes the simulation suite), and
+* *The abacus cosmological N-body code*, `Garrison et al. (2021) <https://academic.oup.com/mnras/article/508/1/575/6366254>`__ (describes the code).
+
+Users of the AbacusSummit CompaSO halo catalogs (which will be most AbacusSummit users) should additionally cite:
+
+* *CompaSO: A new halo finder for competitive assignment to spherical overdensities*, `Hadzhiyska et al. (2021) <https://academic.oup.com/mnras/advance-article/doi/10.1093/mnras/stab2980/6402914>`__ (the CompaSO group finding method)
+
+Users of the AbacusSummit halo light cone catalogs should cite:
+
+* *The halo light cone catalogues of AbacusSummit*, `Hadzhiyska et al. (2021) <https://academic.oup.com/mnras/advance-article/doi/10.1093/mnras/stab3066/6408495>`__ (the generation of halo catalogs on the light cone)
+
+Users of the AbacusSummit merger trees should cite:
+
+* *Constructing high-fidelity halo merger trees in abacussummit*, `Bose et al. (2022) <https://academic.oup.com/mnras/article/512/1/837/6541858>`__ (the merger tree method)
+
+Users of the AbacusHOD module (:doc:`abacusutils:hod`) should cite:
+
+* *AbacusHOD: a highly efficient extended multitracer HOD framework and its application to BOSS and eBOSS data*, `Yuan  et al. (2021) <https://academic.oup.com/mnras/article/510/3/3301/6446006>`__
+
+
+Additional citations of Abacus (which might be used when a work goes beyond just using AbacusSummit data products and is discussing the Abacus code itself) are:
+
+* *A high-fidelity realization of the Euclid code comparison N-body simulation with ABACUS*, `Garrison et al. (2019) <https://academic.oup.com/mnras/article/485/3/3370/5371170>`__ (performance and accuracy of Abacus on the Euclid code comparison simulation, `Schneider et al. (2016) <https://iopscience.iop.org/article/10.1088/1475-7516/2016/04/047>`__)
+* *The Abacus Cosmos: A suite of cosmological N-body simulations*, `Garrison et al. (2018) <https://iopscience.iop.org/article/10.3847/1538-4365/aabfd3>`__ (an early suite of 125 simulations from 40 cosmologies, https://lgarrison.github.io/AbacusCosmos/),
+* *Improving initial conditions for cosmological N-body simulations*, `Garrison et al. (2016) <https://academic.oup.com/mnras/article/461/4/4125/2608725>`__ (detailing the initial conditions method)
+* *A fast N-body scheme for computational cosmology*, `Metchnik (2009) <https://ui.adsabs.harvard.edu/abs/2009PhDT.......175M/abstract>`__ (the inception of the mathematical method for the force solver).
+
+Other Abacus citations may be requested as we publish more of the numerical methods.
+
+A related series of papers investigating the accuracy of Abacus and N-body simulations in general using scale-free simulations may be of interest as well:
+
+* *Accuracy of power spectra in dissipationless cosmological simulations*, `Maleubre et al. (2022) <https://academic.oup.com/mnras/article/512/2/1829/6544652>`__ (likewise assesses the accuracy of power spectra)
+* *Self-similarity of k-nearest neighbour distributions in scale-free simulations*, `Garrison, Abel, and Eisenstein (2021) <https://academic.oup.com/mnras/article/509/2/2281/6414535>`__
+* *Good and proper: self-similarity of N-body simulations with proper force softening*, `Garrison et al. (2021) <https://academic.oup.com/mnras/article/504/3/3550/6246417>`__ (validates the force softening scheme using scale-free simulations)
+* *Quantifying resolution in cosmological N-body simulations using self-similarity*, `Joyce et al. (2021) <https://academic.oup.com/mnras/article/501/4/5051/5979795>`__ (describes accuracy tests using scale-free simulations)

docs/conf.py

@@ -19,25 +19,25 @@
 
 # LHG: this is the author order of the AbacusSummit paper, plus the Phil from the ALCC proposal
 project = 'AbacusSummit'
-copyright = '2021, Nina Maksimova, Lehman Garrison, Daniel Eisenstein, Boryana Hadzhiyska, Sownak Bose, Thomas Satterthwaite, and Philip Pinto'
-author = 'Nina Maksimova, Lehman Garrison, Daniel Eisenstein, Boryana Hadzhiyska, Sownak Bose, Thomas Satterthwaite, and Philip Pinto'
+copyright = '2023, Nina Maksimova, Lehman Garrison, Daniel Eisenstein, Boryana Hadzhiyska, Sownak Bose, Thomas Satterthwaite, and Philip Pinto'
 
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['readthedocs_ext.readthedocs', 'recommonmark', 'sphinx.ext.intersphinx', 'sphinx.ext.autosectionlabel']
+extensions = ['sphinx.ext.intersphinx',
+              'sphinx.ext.autosectionlabel']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-
+exclude_patterns = ['_build']
+root_doc = "index"
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -46,17 +46,34 @@
 #
 #html_theme = 'alabaster'
 #html_theme = 'default'
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'sphinx_book_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+html_css_files = ['custom.css']
 
+html_title = "AbacusSummit"
+html_logo = "images/AbacusSummit_logo_bw.png"
 html_favicon = 'images/icon_red.png'
 
-def setup(app):
-    app.add_css_file('custom.css')
+html_show_sourcelink = False
+html_theme_options = {
+    "repository_url": "https://github.com/abacusorg/AbacusSummit",
+    "repository_branch": "master",
+    # "launch_buttons": {
+    #     "binderhub_url": "https://mybinder.org",
+    #     "notebook_interface": "jupyterlab",
+    #     "colab_url": "https://colab.research.google.com/",
+    # },
+    "use_edit_page_button": True,
+    "use_issues_button": True,
+    "use_repository_button": True,
+    "use_download_button": True,
+    "use_fullscreen_button": False,
+    "logo_only": True,
+}
 
 intersphinx_mapping = {'abacusutils': ('https://abacusutils.readthedocs.io/en/latest', None)}
 

docs/cosmologies.rst

@@ -49,21 +49,23 @@ neutrinos as a smooth component.
 Cosmologies Table
 -----------------
 
-Download the cosmologies table `here <https://github.com/abacusorg/AbacusSummit/blob/master/Cosmologies/cosmologies.csv>`_.
-However, in analysis applications, users are encouraged to use the cosmological parameters stored as in the ``header`` field
+The following is a listing of all cosmologies used in AbacusSummit simulations.
+You can also download the cosmologies table as a CSV `here <https://github.com/abacusorg/AbacusSummit/blob/master/Cosmologies/cosmologies.csv>`__.
+
+In analysis applications, users are encouraged to use the cosmological parameters stored as in the ``header`` field
 of the ASDF data product files (which is loaded into the ``meta`` field of Astropy tables, or the ``header`` field of
 ``CompaSOHaloCatalog`` objects) rather than referencing the cosmologies table.
 
+Another way to access the cosmology of a particular AbacusSummit simulation is
+through the ``abacusnbody.metadata`` module: :doc:`abacusutils:metadata`
+
 Column Names
   The names of the parameter columns in the following table correspond to CLASS parameters.  A good place to look
   for CLASS parameter definitions is this well-commented file:
   `abacus_base.pre <https://github.com/abacusorg/AbacusSummit/blob/master/Cosmologies/abacus_base.pre>`_.
   It is derived from the example CLASS input file, so most of the comments are CLASS's.
   Note that this file is also the base AbacusSummit parameter file used to :ref:`run CLASS<cosmologies:Running CLASS>`.
-  For the full CLASS documentation, see `here <https://lesgourg.github.io/class_public/class.html#documentation>`_.
-
-
-.. note:: The following table is wide, you may have to scroll to the right to see all the columns.
+  For the full CLASS documentation, see `here <https://lesgourg.github.io/class_public/class.html#documentation>`__.
 
 .. csv-table::
     :file: ../Cosmologies/cosmologies.csv

docs/data-products.rst

@@ -279,7 +279,7 @@ the inner 90% of the mass relative to this center.
    [0,30000].
 
 Halo light cone catalogs
-~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~
 The halo light cone catalogs contain several additional fields listed below.
 
 - ``int64_t index_halo``: Index of the halo into the full redshift catalogue

docs/index.rst

@@ -2,10 +2,6 @@
    sphinx-quickstart on Wed Apr 29 14:38:47 2020.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
-
-.. image:: images/AbacusSummit_logo_bw.png
-  :width: 300px
-  :align: center
   
 AbacusSummit
 ============
@@ -18,7 +14,7 @@ Computing Facility under a time allocation from the DOE's ALCC program.
 
 AbacusSummit was run using the Abacus N-body code.  For more information about the code, see :doc:`abacus`.
 
-The specifications of the ~150 simulations that comprise AbacusSumit are given on the :doc:`simulations` page.
+The specifications of the 160+ simulations that comprise AbacusSumit are given on the :doc:`simulations` page.
 
 The cosmologies used by these simulations are specified on the :doc:`cosmologies` page.
 

docs/nbody-details.rst

@@ -7,7 +7,7 @@ that affect the accuracy of the outputs (e.g. softening, time stepping, ICs).
 All of the simulations start at *z* = 99 utilizing second-order Lagrangian
 Perturbation Theory initial conditions following corrections of
 first-order particle linear theory; these are described in Garrison
-et al. (2016, see :ref:`papers`) and have a target correction redshift of 12.  The 
+et al. (2016, see :doc:`citation`) and have a target correction redshift of 12.  The 
 particles are displaced from a cubic grid.
 
 The simulations use spline force softening, described in Garrison
@@ -24,7 +24,7 @@ by a parameter eta, which is 0.25 in these simulations.  Simulations
 require about 1100 time steps to reach *z* = 0.1.
 
 Users of the outputs probably don't need to know much of the numerical
-details of the code, but there is one numerical concept that enter
+details of the code, but there is one numerical concept that enters
 into the data products.  Abacus uses a cubic grid of size CPD\ :sup:`3`,
 chosen to tune code speed.  For AbacusSummit, CPD is ususally 1701.
 Processing proceeds in y-z slabs of cells, and particle outputs are

docs/requirements.txt

@@ -1,2 +1,2 @@
-sphinx >= 3.0.3
-sphinx-rtd-theme >= 1.0.0rc1
+sphinx >= 4.2
+sphinx_book_theme >= 0.3

docs/simulations.rst

@@ -73,14 +73,13 @@ and ph4999 will be irregular.
 Simulations Table
 -----------------
 
-Download the simulations table `here <https://github.com/abacusorg/AbacusSummit/blob/master/Simulations/simulations.csv>`_.
+The following is a complete listing of the AbacusSummit simulations.
+You can also download this table as a CSV file `here <https://github.com/abacusorg/AbacusSummit/blob/master/Simulations/simulations.csv>`_.
 
-The cosmologies in the "Cosm" column are tabulated in :doc:`cosmologies`.
+The numbers in the "Cosm" column correspond to cosmologies in the :ref:`cosmologies:Cosmologies Table`.
 
 The "PPD" column is the number of particles-per-dimension.
 
-.. note:: The following table is wide, you may have to scroll to the right to see all the columns.
-
 .. csv-table::
     :file: ../Simulations/simulations.csv
     :header-rows: 1