docs: fix Sphinx build warnings (#834)

* docs: fix undefined RST substitution in effect_summary docstring

The |effect| notation was being parsed by docutils as an RST
substitution reference, causing an ERROR in the Sphinx build.
Wrapped in double backticks to render as a literal code span.

* docs: fix bullet list indentation in PropensityScore.fit_outcome_model

Continuation lines of RST bullet items must be indented to align
with the text after the `- ` marker. The misaligned lines caused a
"bullet list ends without a blank line; unexpected unindent" WARNING
in the Sphinx build.

* docs: remove __init__ from autosummary methods toctree

autoclass already documents __init__ inline on the class page.
Listing it again in the methods autosummary caused ~30 duplicate
object description WARNINGs (one per public class). Excluding it
from the toctree loop removes the redundant standalone pages.

* docs: switch bibtex style from unsrt to alpha to fix duplicate labels

With bibtex_default_style="unsrt", each per-document bibliography
(filtered with :filter: docname in docnames) assigns sequential
numeric labels [1], [2], ... starting from 1. These collide in
Sphinx's global label registry when the same or different cite keys
appear across multiple documents, producing dozens of
bibtex.duplicate_label and bibtex.duplicate_citation WARNINGs.

Changing to "alpha" gives each entry a unique key derived from
author and year (e.g. [Sha02]), eliminating cross-document clashes.

* docs: fix notebook heading hierarchy to eliminate myst.header WARNINGs

MyST-NB warns when a document's first heading is not H1, or when
heading levels increase non-consecutively (e.g. H2 -> H4).

- structural_causal_models.ipynb: promote title ## -> #; promote
  orphan #### subsections (before first ###) to ##
- inv_prop_latent.ipynb: promote title ## -> #; fix #### -> ## for
  the Brief Digression subheading
- iv_pymc.ipynb: fix ### Comparison to OLS -> ## (H1 -> H3 jump)
- iv_vs_priors.ipynb: promote title ## -> #; restructure cell 4
  from #### to ## / ### to match the two-topic (S&S / Horseshoe)
  organisation
- iv_weak_instruments.ipynb: promote title ## -> #; fix
  #### Digression -> ### (H2 -> H4 jump)

* docs: enable myst_heading_anchors to fix broken xref links in estimands.md

estimands.md links into quasi_dags.ipynb using slug anchors such as
that exist in the notebook, but MyST never registered them as cross-
reference targets because myst_heading_anchors defaulted to 0.

Setting myst_heading_anchors = 3 makes MyST auto-generate anchors for
all H1–H3 headings across all documents, resolving the four
myst.xref_missing WARNINGs without requiring explicit (label)= markers.

* docs: consolidate bibliography into a single global references page

bibtex.duplicate_citation fires when the same cite key appears in
multiple documents that each have their own {bibliography} block. There
were 18 duplicate keys across 23 documents (~28 warnings). The warning
is emitted by sphinxcontrib-bibtex when the same key is registered more
than once in its global citation registry via citation-list bibliography
blocks.

Replace 22 per-document {bibliography} blocks with a single central
bibliography on a new references.rst page. Each cite key is now
registered exactly once, eliminating all duplicate_citation warnings.
The {cite:p}/{cite:t} inline citations across all notebooks are
unchanged — they still resolve correctly via Sphinx's cross-document
reference machinery.

Changes:
- docs/source/references.rst (new): single .. bibliography:: directive
- docs/source/index.md: add references to toctree
- 22 notebooks/markdown files: remove per-page {bibliography} blocks
  and their ## References / ### References headings
- docs/source/knowledgebase/glossary.rst: unchanged (uses footcite)

* docs: normalize whitespace in Hernan2024-HERCIW bib entry

Tabs replaced with spaces by prek on commit. No content change.

* docs: update reference on linden2015

* docs: exclude License section from README include to fix myst.xref_missing

The README's [Apache License 2.0](LICENSE) link is a relative path
that works on GitHub but causes a myst.xref_missing warning when
Sphinx includes the README — there is no LICENSE document in the
docs source tree.

Add a <!-- docs-end --> marker before the License section and update
the {include} directive with :end-before: so Sphinx stops there.
The license is still visible on GitHub via the README.

* docs: fix toc.not_included and trailing transition warnings

- Add rd_skl_drinking.ipynb to the Regression Discontinuity toctree;
  the notebook existed but was missing from the index, causing a
  toc.not_included WARNING.
- Remove trailing --- from estimands.md; a document-level transition
  (horizontal rule) as the last element is invalid in docutils and
  caused a WARNING: Document may not end with a transition.

* docs: fix LICENSE link in README to resolve myst.xref_missing

Replace the relative path (LICENSE) with an absolute URL so MyST
treats it as an external link rather than an internal cross-reference.
Removes the <!-- docs-end --> workaround so the License section is
now included in the rendered Sphinx docs as well.

* docs: restore notebook metadata to match main

* docs: move references page under knowledge base

* docs: strip citekey labels from references page with post-transform

Author: anevolbap

README.md

@@ -166,4 +166,4 @@ Plans for the repository can be seen in the [Issues](https://github.com/pymc-lab
 
 ## License
 
-[Apache License 2.0](LICENSE)
+[Apache License 2.0](https://github.com/pymc-labs/CausalPy/blob/main/LICENSE)

causalpy/experiments/base.py

@@ -354,7 +354,8 @@ def effect_summary(
             (ITS/SC only, ignored for DiD/RD)
         min_effect : float, optional
             Region of Practical Equivalence (ROPE) threshold (PyMC only, ignored for OLS).
-            If provided, reports P(|effect| > min_effect) for two-sided or P(effect > min_effect) for one-sided.
+            If provided, reports ``P(|effect| > min_effect)`` for two-sided or
+            ``P(effect > min_effect)`` for one-sided.
         treated_unit : str, optional
             For multi-unit experiments (Synthetic Control), specify which treated unit
             to analyze. If None and multiple units exist, uses first unit.

causalpy/pymc_models.py

@@ -1329,13 +1329,13 @@ def fit_outcome_model(
         Notes
         -----
         - This model uses a sampled version of the propensity score (`p`) from the
-        posterior of the treatment model, randomly selecting one posterior draw
-        per call. This term is estimated initially in the InversePropensity
-        class initialisation.
+          posterior of the treatment model, randomly selecting one posterior draw
+          per call. This term is estimated initially in the InversePropensity
+          class initialisation.
         - The term `beta_ps[0] * p` captures both
-        main effects of the propensity score.
+          main effects of the propensity score.
         - Including spline adjustment enables modeling nonlinear relationships
-        between the propensity score and the outcome.
+          between the propensity score and the outcome.
 
         """
         if priors is None:

docs/source/_extensions/strip_citation_labels.py

@@ -0,0 +1,21 @@
+"""Strip citation labels ([Aba21]) from bibliography entries."""
+
+import docutils.nodes
+from sphinx.transforms.post_transforms import SphinxPostTransform
+
+
+class StripCitationLabels(SphinxPostTransform):
+    default_priority = 6  # runs right after BibliographyTransform (priority 5)
+
+    def run(self):
+        for node in self.document.findall(docutils.nodes.citation):
+            for label in node.findall(docutils.nodes.label):
+                label.parent.remove(label)
+            for para in node.findall(docutils.nodes.paragraph):
+                para.insert(0, docutils.nodes.Text("\u2022 "))
+                break
+
+
+def setup(app):
+    app.add_post_transform(StripCitationLabels)
+    return {"version": "0.1", "parallel_read_safe": True, "parallel_write_safe": True}

docs/source/_static/custom.css

@@ -0,0 +1,5 @@
+/* Hanging indent for bibliography entries with bullet markers */
+.citation[role="doc-biblioentry"] p {
+    padding-left: 1em;
+    text-indent: -1em;
+}

docs/source/_templates/autosummary/class.rst

@@ -13,7 +13,9 @@
       :toctree:
 
    {% for item in methods %}
+   {% if item != '__init__' %}
       {{ objname }}.{{ item }}
+   {% endif %}
    {%- endfor %}
    {% endif %}
    {% endblock %}

docs/source/conf.py

@@ -15,6 +15,7 @@
 from causalpy.version import __version__
 
 sys.path.insert(0, os.path.abspath("../"))
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "_extensions"))
 
 # autodoc_mock_imports
 # This avoids autodoc breaking when it can't find packages imported in the code.
@@ -74,6 +75,7 @@
     "sphinx_design",
     "sphinx_sitemap",
     "sphinx_togglebutton",
+    "strip_citation_labels",
 ]
 
 nb_execution_mode = "off"
@@ -94,7 +96,7 @@
 
 # bibtex config
 bibtex_bibfiles = ["references.bib"]
-bibtex_default_style = "unsrt"
+bibtex_default_style = "alpha"
 bibtex_reference_style = "author_year"
 
 
@@ -136,6 +138,7 @@
 
 # MyST options for working with markdown files.
 # Info about extensions here https://myst-parser.readthedocs.io/en/latest/syntax/optional.html?highlight=math#admonition-directives # noqa: E501
+myst_heading_anchors = 3  # auto-generate anchors for H1–H3, enabling #slug cross-refs
 myst_enable_extensions = [
     "dollarmath",
     "amsmath",
@@ -153,6 +156,7 @@
 
 html_theme = "labs_sphinx_theme"
 html_static_path = ["_static"]
+html_css_files = ["custom.css"]
 html_extra_path = ["robots.txt"]
 html_favicon = "_static/favicon_logo.png"
 # Theme options are theme-specific and customize the look and feel of a theme

docs/source/knowledgebase/design_notation.md

@@ -92,8 +92,3 @@ From an analysis perspective, regression discontinuity designs are very similar
 
 ## Summary
 This page has offered a brief overview of the tabular notation used to describe quasi-experimental designs. The notation is a useful tool for summarizing the design of a study, and can be used to help identify the strengths and limitations of a study design. But readers are strongly encouraged to consult the original sources when assessing the relative strengths and limitations of making causal claims under different quasi-experimental designs.
-
-## References
-:::{bibliography}
-:filter: docname in docnames
-:::

docs/source/knowledgebase/estimands.md

@@ -147,11 +147,3 @@ The descriptions above assume standard usage. Always consider what your specific
 | Regression Discontinuity | Local treatment effect at cutoff | Prediction-based |
 
 For methods not covered in detail here (IV, IPW, ANCOVA), see the respective notebook documentation, {doc}`quasi_dags` for identification, and the {doc}`glossary` for estimand definitions. Note that some of these methods have more limited implementation support in CausalPy---for example, IV does not yet have full `plot()` and `summary()` support, and IPW and ANCOVA are Bayesian-only.
-
----
-
-## References
-
-:::{bibliography}
-:filter: docname in docnames
-:::

docs/source/knowledgebase/index.md

@@ -12,4 +12,5 @@ structural_causal_models.ipynb
 custom_pymc_models.ipynb
 causal_video_resources
 causal_written_resources
+../references
 :::