DOC: start overhaul of documentation (#94)

* DOC: start overhaul of documentation * DOC: fix typo in example paths * DOC: add a user guide
ColmTalbot · Jun 15, 2024 · 2daa71e · 2daa71e
1 parent ba0f4c5
commit 2daa71e
Show file tree

Hide file tree

Showing 30 changed files with 2,305 additions and 534 deletions.
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -46,7 +46,7 @@ jobs:
 
       - name: Build documentation
         run: |
-          cp examples/*.ipynb docs
+          cp examples/*.ipynb docs/examples
           cd docs
           make clean
           make html

diff --git a/.gitignore b/.gitignore
@@ -1,17 +1,22 @@
 *.ignore
 gwpopulation.egg-info
 build/*
-outdir/*
+outdir
 logs/*
 **/__pycache__/*
 __pycache__/*
 */_build/
 */.ipynb*
 .coverage
+.coverage.*
 venv/
 .idea/
 **/.version
 **/_version.py
 .vscode
 .ipynb_checkpoints*
 */*/.ipynb*
+examples/*.pkl
+examples/*.tar.gz
+examples/*.py
+examples/GWTC-1_sample_release
diff --git a/README.md b/README.md
@@ -1,11 +1,14 @@
 [![Python package](https://github.com/ColmTalbot/gwpopulation/actions/workflows/python-package.yml/badge.svg)](https://github.com/ColmTalbot/gwpopulation/actions/workflows/python-package.yml)
-[![GitHub Pages](https://github.com/ColmTalbot/gwpopulation/actions/workflows/pages.yml/badge.svg)](https://github.com/ColmTalbot/gwpopulation/actions/workflows/pages.yml)
 [![codecov](https://codecov.io/gh/ColmTalbot/gwpopulation/branch/master/graph/badge.svg?token=4K4V0HRDMI)](https://codecov.io/gh/ColmTalbot/gwpopulation)
-[![Maintainability](https://api.codeclimate.com/v1/badges/579536603e8e06466e63/maintainability)](https://codeclimate.com/github/ColmTalbot/gwpopulation/maintainability)
 [![Versions](https://img.shields.io/pypi/pyversions/gwpopulation.svg)](https://pypi.org/project/gwpopulation/)
+![Conda Downloads](https://img.shields.io/conda/d/conda-forge/gwpopulation)
 
 # GWPopulation
 
+Flexible, extensible, hardware-agnostic gravitational-wave population inference.
+
+`GWPopulation` is the 
+
 A collection of parametric binary black hole mass/spin population models.
 
 These are formatted to be consistent with the [Bilby](https://git.ligo.org/lscsoft/bilby) [hyper-parameter inference package](https://lscsoft.docs.ligo.org/bilby/hyperparameters.html).
@@ -18,24 +21,23 @@ If you're using this for production analyses, you may be interested in the assoc
 
 # Attribution
 
-Please cite [Talbot _et al_ (2019)](https://doi.org/10.1103/PhysRevD.100.043030) if you find this package useful.
+Please cite [Talbot _et al._ (2019)](https://doi.org/10.1103/PhysRevD.100.043030) if you find this package useful.
 
-```
+```bibtex
 @ARTICLE{2019PhRvD.100d3030T,
-       author = {{Talbot}, Colm and {Smith}, Rory and {Thrane}, Eric and
-         {Poole}, Gregory B.},
-        title = "{Parallelized inference for gravitational-wave astronomy}",
-      journal = {\prd},
-         year = 2019,
-        month = aug,
-       volume = {100},
-       number = {4},
-          eid = {043030},
-        pages = {043030},
-          doi = {10.1103/PhysRevD.100.043030},
-archivePrefix = {arXiv},
-       eprint = {1904.02863},
- primaryClass = {astro-ph.IM},
+  author = {{Talbot}, Colm and {Smith}, Rory and {Thrane}, Eric and {Poole}, Gregory B.},
+  title = "{Parallelized inference for gravitational-wave astronomy}",
+  journal = {\prd},
+  year = 2019,
+  month = aug,
+  volume = {100},
+  number = {4},
+  eid = {043030},
+  pages = {043030},
+  doi = {10.1103/PhysRevD.100.043030},
+  archivePrefix = {arXiv},
+  eprint = {1904.02863},
+  primaryClass = {astro-ph.IM},
 }
 ```
 

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1,2 +1,3 @@
 _autosummary
-_build
+_build
+examples/*.ipynb
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,73 +1,44 @@
-# -*- coding: utf-8 -*-
-#
-# population documentation build configuration file, created by
-# sphinx-quickstart on Fri May 25 12:08:01 2018.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
+# -- Project information --------------------------------------------------
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
+import importlib.metadata
 import os
-import sys
-
-import gwpopulation
 
-sys.path.insert(0, os.path.abspath("../"))
+project = "GWPopulation"
+copyright = "2021-2024, Colm Talbot"
+author = "Colm Talbot"
 
 # -- General configuration ------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.mathjax",
     "numpydoc",
     "nbsphinx",
     "sphinx.ext.autosummary",
     "sphinx.ext.viewcode",
+    "autoapi.extension",
+    "myst_parser",
+    "sphinx_design",
+    "sphinx_copybutton",
 ]
-autosummary_generate = True
 
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
+html_static_path = ["_static"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "requirements.txt"]
 
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-source_suffix = [".txt", ".rst"]
-
-# The master toctree document.
-master_doc = "index"
-
-# General information about the project.
-project = "GWPopulation"
-copyright = "2021, Colm Talbot"
-author = "Colm Talbot"
+root_doc = "index"
+source_suffix = [".rst", ".md"]
 
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-fullversion = gwpopulation.__version__.split(":")[0]
+fullversion = importlib.metadata.version("gwpopulation")
 version = ".".join(fullversion.split(".")[:2])
 # The full version, including alpha/beta/rc tags.
-release = fullversion
+release = fullversion.split("+")[0]
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -76,122 +47,87 @@
 # Usually you set "language" from the command line for these cases.
 language = "en"
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "requirements.txt"]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
+# pygments_style = "sphinx"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
+# todo_include_todos = False
 
 
 # -- Options for HTML output ----------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = "sphinx_rtd_theme"
-# html_theme = "alabaster"
+html_theme = "pydata_sphinx_theme"
+
+autosummary_generate = True
+numpydoc_show_class_members = False
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
 # html_theme_options = {}
 
-# 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"]
 
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# This is required for the alabaster theme
-# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
-    "**": [
-        "about.html",
-        "navigation.html",
-        "relations.html",  # needs 'show_related': True theme option to display
-        "searchbox.html",
-        "donate.html",
-    ]
+autoapi_dirs = ["../gwpopulation"]
+autoapi_ignore = ["*_version*"]
+
+json_url = "https://wcosmo.readthedocs.io/en/latest/_static/switcher.json"
+
+version_match = os.environ.get("READTHEDOCS_VERSION")
+# If READTHEDOCS_VERSION doesn't exist, we're not on RTD
+# If it is an integer, we're in a PR build and the version isn't correct.
+# If it's "latest" → change to "dev" (that's what we want the switcher to call it)
+if not version_match or version_match.isdigit() or version_match == "latest":
+    # For local development, infer the version to match from the package.
+    if "dev" in release or "rc" in release:
+        version_match = "dev"
+        # We want to keep the relative reference if we are in dev mode
+        # but we want the whole url if we are effectively in a released version
+        json_url = "_static/switcher.json"
+    else:
+        version_match = f"v{release}"
+elif version_match == "stable":
+    version_match = f"v{release}"
+
+html_theme_options = {
+    "logo": {"text": f"GWPopulation v{version}"},
+    "navbar_center": ["navbar-nav"],
+    # "navbar_start": ["navbar-logo", "version-switcher"],
+    "navbar_start": ["navbar-logo"],
+    "navbar_end": ["theme-switcher", "navbar-icon-links"],
+    "use_edit_page_button": True,
+    "show_version_warning_banner": True,
+    "footer_start": ["copyright"],
+    "footer_center": ["sphinx-version"],
+    # "switcher": {
+    #     "json_url": json_url,
+    #     "version_match": version_match,
+    # },
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/ColmTalbot/GWPopulation",
+            "icon": "fa-brands fa-github",
+        },
+    ],
 }
 
-
-# -- Options for HTMLHelp output ------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = "gwpopulationdoc"
-
-
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
+html_context = {
+    "github_user": "ColmTalbot",
+    "github_repo": "gwpopulation",
+    "github_version": "main",
+    "doc_path": "docs",
 }
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (
-        master_doc,
-        "gwpopulation.tex",
-        "GWPopulation Documentation",
-        "Colm Talbot",
-        "manual",
-    ),
-]
-
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "GWPopulation", "GWPopulation Documentation", [author], 1)]
-
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (
-        master_doc,
-        "GWPopulation",
-        "GWPopulation Documentation",
-        author,
-        "Colm Talbot",
-        "Population models for gravitational waves.",
-        "Miscellaneous",
-    ),
-]
-
-numpydoc_show_class_members = False
-
 nbsphinx_execute = "never"
 nbsphinx_prolog = """
-This page was automatically generated from a Jupyter notebook.
+This page was automatically generated from a Jupyter notebook. Find the original here_.
+
+.. image:: https://colab.research.google.com/assets/colab-badge.svg
+    :target: https://colab.research.google.com/github/ColmTalbot/GWPopulation/blob/main/examples/{{ env.doc2path(env.docname, base=None) }}
 
-Find the original here_.
+.. _here: https://github.com/ColmTalbot/gwpopulation/tree/main/examples/{{ env.doc2path(env.docname, base=None) }}
 
-.. _here: https://github.com/ColmTalbot/gwpopulation/tree/master/examples/{{ env.doc2path(env.docname, base=None) }}
 ----
 """
diff --git a/docs/contributing/code_of_conduct.rst b/docs/contributing/code_of_conduct.rst
@@ -0,0 +1,6 @@
+Code of Conduct
+---------------
+
+We closely follow the `Contributor Covenant Code of Conduct <https://www.contributor-covenant.org/version/2/0/code_of_conduct/>`_
+as described in the `code of conduct <https://github.com/ColmTalbot/GWPopulation/CODE_OF_CONDUCT.md>`_.
+Please read the full text so that you can understand what actions will and will not be tolerated.