Merge pull request #213 from igerber/claude/improve-docs-architecture-8mBgV

Author: igerber

docs/api/index.rst

@@ -214,7 +214,8 @@ Built-in datasets for examples and testing:
 Module Documentation
 --------------------
 
-Detailed documentation by module:
+Estimators
+~~~~~~~~~~
 
 .. toctree::
    :maxdepth: 2
@@ -229,12 +230,33 @@ Detailed documentation by module:
    efficient_did
    two_stage
    bacon
-   results
-   visualization
+
+Diagnostics & Inference
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 2
+
    diagnostics
    honest_did
    power
    pretrends
+
+Results & Visualization
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 2
+
+   results
+   visualization
+
+Data & Utilities
+~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 2
+
    utils
    prep
    datasets

docs/conf.py

@@ -91,7 +91,7 @@
         },
     ],
     "navbar_end": ["theme-switcher", "navbar-icon-links"],
-    "navigation_depth": 4,
+    "navigation_depth": 3,
     "show_toc_level": 2,
 }
 
@@ -107,6 +107,20 @@
 
 # -- Options for nbsphinx ---------------------------------------------------
 nbsphinx_execute = "never"
+nbsphinx_prolog = r"""
+{% set docname = env.doc2path(env.docname, base=None) %}
+
+.. raw:: html
+
+    <div class="admonition note">
+    <p class="admonition-title">Interactive notebook</p>
+    <p>
+    This tutorial is a Jupyter notebook. You can
+    <a href="https://github.com/igerber/diff-diff/blob/main/docs/{{ docname }}">view it on GitHub</a>
+    or download it to run locally.
+    </p>
+    </div>
+"""
 
 # -- Options for intersphinx -------------------------------------------------
 intersphinx_mapping = {

docs/index.rst

@@ -44,54 +44,71 @@ For development:
 Quick Links
 -----------
 
-- :doc:`api/index` - Full API reference
-- :doc:`quickstart` - Get started with basic examples
+- :doc:`quickstart` - Installation and your first DiD analysis
 - :doc:`choosing_estimator` - Which estimator should I use?
+- :doc:`tutorials/01_basic_did` - Hands-on basic tutorial
 - :doc:`troubleshooting` - Common issues and solutions
-- :doc:`r_comparison` - Comparison with R packages
-- :doc:`python_comparison` - Comparison with Python packages
-- :doc:`benchmarks` - Validation benchmarks vs R
-
-.. toctree::
-   :maxdepth: 2
-   :caption: API
-   :hidden:
-
-   api/index
+- :doc:`r_comparison` - Coming from R?
+- :doc:`api/index` - Full API reference
 
 .. toctree::
    :maxdepth: 2
-   :caption: Guide
+   :caption: Getting Started
    :hidden:
 
    quickstart
    choosing_estimator
    troubleshooting
-   r_comparison
-   python_comparison
-   benchmarks
 
 .. toctree::
    :maxdepth: 1
-   :caption: Tutorials
+   :caption: Tutorials: Fundamentals
    :hidden:
 
    tutorials/01_basic_did
    tutorials/02_staggered_did
    tutorials/03_synthetic_did
-   tutorials/04_parallel_trends
-   tutorials/05_honest_did
-   tutorials/06_power_analysis
-   tutorials/07_pretrends_power
    tutorials/08_triple_diff
    tutorials/09_real_world_examples
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Tutorials: Advanced Methods
+   :hidden:
+
    tutorials/10_trop
    tutorials/11_imputation_did
    tutorials/12_two_stage_did
    tutorials/13_stacked_did
    tutorials/14_continuous_did
    tutorials/15_efficient_did
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Tutorials: Study Design
+   :hidden:
+
+   tutorials/04_parallel_trends
+   tutorials/05_honest_did
+   tutorials/06_power_analysis
+   tutorials/07_pretrends_power
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Comparisons & Benchmarks
+   :hidden:
+
+   r_comparison
+   python_comparison
+   benchmarks
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API Reference
+   :hidden:
+
+   api/index
+
 What is Difference-in-Differences?
 ----------------------------------
 

docs/llms-full.txt

@@ -2,7 +2,7 @@
 
 > A Python library for Difference-in-Differences causal inference analysis. Provides sklearn-like estimators with statsmodels-style output for econometric analysis.
 
-- Version: 2.7.1
+- Version: 2.7.2
 - Repository: https://github.com/igerber/diff-diff
 - License: MIT
 - Dependencies: numpy, pandas, scipy (no statsmodels dependency)

docs/llms.txt

@@ -12,13 +12,21 @@ diff-diff offers 14 estimators covering basic 2x2 DiD, modern staggered adoption
 
 ## Documentation
 
-- [Quickstart](https://diff-diff.readthedocs.io/en/stable/quickstart.html): Get started with basic examples — column-name and formula interfaces, covariates, fixed effects, cluster-robust SEs
+### Getting Started
+
+- [Quickstart](https://diff-diff.readthedocs.io/en/stable/quickstart.html): Installation, basic 2x2 DiD — column-name and formula interfaces, covariates, fixed effects, cluster-robust SEs
 - [Choosing an Estimator](https://diff-diff.readthedocs.io/en/stable/choosing_estimator.html): Decision flowchart for selecting the right estimator for your research design
-- [API Reference](https://diff-diff.readthedocs.io/en/stable/api/index.html): Full API documentation for all estimators, results classes, diagnostics, and utilities
+- [Troubleshooting](https://diff-diff.readthedocs.io/en/stable/troubleshooting.html): Common issues and solutions
+
+### Comparisons & Benchmarks
+
 - [R Comparison](https://diff-diff.readthedocs.io/en/stable/r_comparison.html): Side-by-side comparison with R packages (did, fixest, synthdid, didimputation, did2s, stackedev)
 - [Python Comparison](https://diff-diff.readthedocs.io/en/stable/python_comparison.html): Comparison with Python DiD packages
 - [Benchmarks](https://diff-diff.readthedocs.io/en/stable/benchmarks.html): Validation results and performance benchmarks vs R
-- [Troubleshooting](https://diff-diff.readthedocs.io/en/stable/troubleshooting.html): Common issues and solutions
+
+### API Reference
+
+- [API Reference](https://diff-diff.readthedocs.io/en/stable/api/index.html): Full API documentation for all estimators, results classes, diagnostics, and utilities
 
 ## Estimators