DOC: change documentation theme and neaten up build

.github/workflows/pages.yml

@@ -38,7 +38,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          python -m pip install -r doc/pages_requirements.txt
+          conda install --file doc/pages_requirements.txt
           python -m pip install .
 
       - name: Build documentation

.gitignore

@@ -3,3 +3,4 @@
 build/
 doc/build/
 doc/source/api/
+wcosmo/_version.py

.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+repos:
+-   repo: https://github.com/ambv/black
+    rev: 24.4.2
+    hooks:
+      - id: black
+        language_version: python3
+-   repo: https://github.com/ambv/black
+    rev: 24.4.2
+    hooks:
+      - id: black-jupyter
+        language_version: python3
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+    -   id: check-merge-conflict # prevent committing files with merge conflicts
+-   repo: https://github.com/codespell-project/codespell
+    rev: v2.3.0
+    hooks:
+    -   id: codespell # Spellchecker
+        args: [-L, "nd,hist", "--skip", "*.ipynb"]
+-   repo: https://github.com/pre-commit/mirrors-isort
+    rev: v5.10.1
+    hooks:
+    -   id: isort # sort imports alphabetically and separates import into sections
+        args: [-w=88, -m=3, --tc, -sp=setup.cfg ]
+-   repo: local
+    hooks:
+    -   id: flynt
+        name: flynt
+        entry: flynt
+        args: [--fail-on-change]
+        types: [python]
+        language: python
+        additional_dependencies:
+            - flynt

README.rst

@@ -1,16 +1,35 @@
 Backend agnostic astropy-like cosmology
 =======================================
 
-The primary intention for this package is for use with :code:`GWPopulation`
-but the main functionality can be used externally.
+An efficient implementation of :code:`astropy`-like cosmology compatible
+with :code:`numpy`-like backends, e.g., :code:`jax` and :code:`cupy`.
+
+There are two main features leading to superior efficiency to :code:`astropy`:
+
+- Integrals of :math:`E(z)` and related functions are performed analytically
+  with Pade approximations.
+- Support for :code:`jax` and :code:`cupy` backends allow hardware
+  acceleration, just-in-time compilation, and automatic differentiation.
+- We don't use explicit units, which can be a source of inefficiency.
+
+The primary limitations are:
+
+- Only flat cosmologies are supported with two components with constant
+  equations of state, e.g., :code:`FlatwCDM`.
+- Approximations to the various integrals generally agree with :code:`astropy`
+  at the 0.1% level.
+- The units we use are documented, but users need to be careful.
 
 Installation and contribution
 -----------------------------
 
-Currently installation is only available from source
+:code:`wcosmo` can be installed via :code:`conda-forge`, :code:`pypi` or from
+source.
 
 .. code-block:: console
 
+    $ mamba install -c conda-forge wcosmo
+    $ pip install wcosmo
     $ pip install git+https://github.com/ColmTalbot/wcosmo.git
 
 for development you should follow a standard fork-and-pull workflow.
@@ -42,12 +61,16 @@ To import an astropy-like cosmology (without units)
     from wcosmo import FlatwCDM
     cosmology = FlatwCDM(H0=70, Om0=0.3, w0=-1)
 
+GWPopulation
+^^^^^^^^^^^^
+
+The primary intention for this package is for use with :code:`GWPopulation`.
 This code is automatically used in :code:`GWPopulation` when using either
 :code:`gwpopulation.experimental.cosmo_models.CosmoModel` and/or
 :code:`PowerLawRedshift`
 
 Changing backend
-----------------
+^^^^^^^^^^^^^^^^
 
 The backend can be switched automatically using, e.g.,
 

doc/pages_requirements.txt

@@ -6,4 +6,4 @@ pandoc
 pygments
 sphinx
 sphinx_rtd_theme
-sphinx-nefertiti
+pydata-sphinx-theme

doc/source/api/index.rst

@@ -0,0 +1,14 @@
+API Reference
+-------------
+
+.. currentmodule:: wcosmo
+
+.. autosummary::
+   :toctree: .
+   :template: custom-module-template.rst
+   :caption: API
+   :recursive:
+
+   taylor
+   utils
+   wcosmo

doc/source/conf.py

@@ -5,35 +5,36 @@
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import importlib.metadata
 
-project = 'wcosmo'
-copyright = '2024, Colm Talbot, Amanda Farah'
-author = 'Colm Talbot, Amanda Farah'
-release = '0.0.0'
+project = "wcosmo"
+copyright = "2024, Colm Talbot, Amanda Farah"
+author = "Colm Talbot, Amanda Farah"
+release = importlib.metadata.version("wcosmo").split("+")[0]
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.githubpages',
-    'sphinx.ext.autosummary',
-    'numpydoc',
-    'nbsphinx',
-    'sphinx.ext.viewcode',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.autosummary",
+    "numpydoc",
+    "nbsphinx",
+    "sphinx.ext.viewcode",
 ]
 
-templates_path = ['_templates']
+templates_path = ["_templates"]
 exclude_patterns = []
 
-root_doc = 'index'
+root_doc = "index"
 
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'sphinx_nefertiti'
-html_static_path = ['_static']
+html_theme = "pydata_sphinx_theme"
 
 autosummary_generate = True
+numpydoc_show_class_members = False

doc/source/examples/index.rst

@@ -0,0 +1,5 @@
+Examples
+========
+
+.. attention::
+   No example notebooks are available yet.

doc/source/index.rst

@@ -2,24 +2,18 @@
 
 .. include:: ../../README.rst
 
+Examples
+--------
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-
-
-.. autosummary::
-   :toctree: api
-   :template: custom-module-template.rst
-   :caption: API
-   :recursive:
 
-   wcosmo
-   utils
+   Examples <examples/index>
 
+API Reference
+-------------
 
-Indices and tables
-==================
+.. toctree::
+   :maxdepth: 2
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   API <api/index>