Merge pull request #354 from OriolAbril/docs

Documentation infrastructure

Author: drbenvincent

.github/workflows/rtd-link-preview.yml

@@ -0,0 +1,16 @@
+name: Read the Docs Pull Request Preview
+on:
+  pull_request_target:
+    types:
+      - opened
+
+permissions:
+  pull-requests: write
+
+jobs:
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "causalpy"

.gitignore

@@ -7,6 +7,8 @@ _build
 build/
 dist/
 docs/_build/
+docs/build/
+docs/jupyter_execute/
 *.vscode
 .coverage
 *.jupyterlab-workspace

.readthedocs.yaml

@@ -7,9 +7,9 @@ version: 2
 
 # Set the version of Python and other tools you might need
 build:
-  os: ubuntu-20.04
+  os: ubuntu-lts-latest
   tools:
-    python: "3.10"
+    python: "3.11"
     # You can also specify other tool versions:
     # nodejs: "16"
     # rust: "1.55"

README.md

@@ -34,7 +34,7 @@ pip install git+https://github.com/pymc-labs/CausalPy.git
 
 ```python
 import causalpy as cp
-
+import matplotlib.pyplot as plt
 
 # Import and process data
 df = (
@@ -57,6 +57,8 @@ fig, ax = result.plot();
 
 # Get a results summary
 result.summary()
+
+plt.show()
 ```
 
 ## Roadmap

docs/source/conf.py

@@ -51,11 +51,18 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
     "sphinx_autodoc_typehints",
+    "sphinx_copybutton",
 ]
 
 nb_execution_mode = "off"
 
+# configure copy button to avoid copying sphinx or console characters
+copybutton_exclude = ".linenos, .gp"
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
+
 source_suffix = {
     ".rst": "restructuredtext",
     ".ipynb": "myst-nb",
@@ -72,8 +79,15 @@
 
 # -- intersphinx config -------------------------------------------------------
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3", None),
+    "examples": ("https://www.pymc.io/projects/examples/en/latest/", None),
+    "mpl": ("https://matplotlib.org/stable", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
     "pymc": ("https://www.pymc.io/projects/docs/en/stable/", None),
+    "python": ("https://docs.python.org/3", None),
+    "scikit-learn": ("https://scikit-learn.org/stable/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "xarray": ("https://docs.xarray.dev/en/stable/", None),
 }
 
 # MyST options for working with markdown files.

docs/source/index.rst

@@ -12,12 +12,18 @@ A Python package focussing on causal inference for quasi-experiments. The packag
 Installation
 ------------
 
-To get the latest release:
+To get the latest release you can use pip:
 
 .. code-block:: sh
 
    pip install CausalPy
 
+or conda:
+
+.. code-block:: sh
+
+   conda install causalpy -c conda-forge
+
 Alternatively, if you want the very latest version of the package you can install from GitHub:
 
 .. code-block:: sh
@@ -31,6 +37,7 @@ Quickstart
 .. code-block:: python
 
    import causalpy as cp
+   import matplotlib.pyplot as plt
 
 
    # Import and process data
@@ -55,6 +62,8 @@ Quickstart
    # Get a results summary
    result.summary()
 
+   plt.show()
+
 
 Videos
 ------

pyproject.toml

@@ -54,12 +54,12 @@ docs = [
     "ipykernel",
     "daft",
     "linkify-it-py",
-    "myst-nb<=1.0.0",
+    "myst-nb!=1.1.0",
     "pathlib",
     "sphinx",
     "sphinx-autodoc-typehints",
     "sphinx_autodoc_defaultargs",
-    "sphinx-design",
+    "sphinx-copybutton",
     "sphinx-rtd-theme",
     "statsmodels",
     "sphinxcontrib-bibtex",