fix docs (#185)

Fixes missing entry for `bootstrap.covariance` in the docs and adds the tag and probe example to the docs. The changelog now points to Github for the more recent updates. Switch to RTD theme and fix the unwieldly function signatures.
scikit-hep · Apr 19, 2024 · a91ffad · a91ffad
1 parent 595a6d4
commit a91ffad
Show file tree

Hide file tree

Showing 8 changed files with 50 additions and 182 deletions.
diff --git a/doc/changelog.rst b/doc/changelog.rst
@@ -1,10 +1,7 @@
 Changelog
 =========
 
-1.5.2 (October 15, 2022)
-------------------------------------------------
-- Update ci skripts and fix types (`#154 <https://github.com/scikit-hep/iminuit/pull/154>`_)
-- Fix extended (`#153 <https://github.com/scikit-hep/iminuit/pull/153>`_)
+For more recent versions, please look into `the release notes on Github <https://github.com/scikit-hep/resample/releases>`_.
 
 1.5.1 (March 1, 2022)
 ---------------------

diff --git a/doc/conf.py b/doc/conf.py
@@ -40,6 +40,11 @@
     "nbsphinx",
 ]
 
+autoclass_content = "both"
+autosummary_generate = True
+autodoc_member_order = "groupwise"
+autodoc_type_aliases = {"ArrayLike": "ArrayLike"}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -76,21 +81,16 @@
 
 # -- 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 = "alabaster"
+import sphinx_rtd_theme
+
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # 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 = {
-    "logo": "logo.svg",
-    "description": "Version " + version,
-    "github_user": "resample-project",
-    "github_repo": "resample",
-}
+html_logo = "_static/logo.svg"
 
 # 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,
@@ -111,74 +111,3 @@
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = "resampledoc"
-
-
-# -- 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',
-}
-
-# 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, "resample.tex", "resample Documentation", "Daniel Saxton", "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, "resample", "resample 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,
-        "resample",
-        "resample Documentation",
-        author,
-        "resample",
-        "One line description of project.",
-        "Miscellaneous",
-    )
-]
-
-
-# -- Options for Epub output -------------------------------------------------
-
-# Bibliographic Dublin Core info.
-epub_title = project
-
-# The unique identifier of the text. This can be a ISBN number
-# or the project homepage.
-#
-# epub_identifier = ''
-
-# A unique identification for the text.
-#
-# epub_uid = ''
-
-# A list of files that should not be packed into the epub file.
-epub_exclude_files = ["search.html"]
-
-
-# -- Extension configuration -------------------------------------------------
diff --git a/doc/example/tag_and_probe.ipynb b/doc/example/tag_and_probe.ipynb
diff --git a/doc/examples.rst b/doc/examples.rst
@@ -0,0 +1,9 @@
+Examples
+========
+
+These are specific examples which show how to use resample in practice. In contrast to tutorials they are not designed to showcase particular functions in resample.
+
+.. toctree::
+    :maxdepth: 1
+
+    example/tag_and_probe
diff --git a/doc/index.rst b/doc/index.rst
@@ -12,4 +12,5 @@
 
    reference
    tutorials
+   examples
    changelog
diff --git a/doc/update_changelog.py b/doc/update_changelog.py
diff --git a/pyproject.toml b/pyproject.toml
@@ -37,7 +37,7 @@ documentation = "https://resample.readthedocs.io/en/stable/"
 
 [project.optional-dependencies]
 test = ["pytest", "pytest-cov", "coverage[toml]"]
-doc = ["ipython", "nbsphinx"]
+doc = ["ipython", "nbsphinx", "sphinx_rtd_theme"]
 
 [tool.setuptools.packages.find]
 where = ["src"]

diff --git a/src/resample/bootstrap.py b/src/resample/bootstrap.py
@@ -16,6 +16,7 @@
     "resample",
     "bootstrap",
     "variance",
+    "covariance",
     "confidence_interval",
 ]
 
@@ -358,7 +359,7 @@ def covariance(
 
     Examples
     --------
-    Compute variance of arithmetic mean.
+    Compute covariance of sample mean and sample variance.
 
     >>> from resample.bootstrap import variance
     >>> import numpy as np