From a71d4d55a90af620f1eae9c3a1015f05b4a43b28 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 18 Mar 2026 15:16:57 +0000
Subject: [PATCH 1/4] Initial plan


From 34d19f76118d3a5a7affc6e83e5f8c7de7bf8e32 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 18 Mar 2026 15:22:07 +0000
Subject: [PATCH 2/4] docs: add Sphinx+RTD setup and docs build workflow

Co-authored-by: asantini29 <79840851+asantini29@users.noreply.github.com>
---
 .github/workflows/docs.yml | 26 +++++++++++++++++++++++
 .gitignore                 |  1 +
 .readthedocs.yml           | 15 ++++++++++++++
 README.md                  | 33 +++++++++++++++++++++++-------
 docs/conf.py               | 41 +++++++++++++++++++++++++++++++++++++
 docs/index.rst             | 10 +++++++++
 docs/modules.rst           | 42 ++++++++++++++++++++++++++++++++++++++
 docs/requirements.txt      |  2 ++
 8 files changed, 163 insertions(+), 7 deletions(-)
 create mode 100644 .github/workflows/docs.yml
 create mode 100644 .readthedocs.yml
 create mode 100644 docs/conf.py
 create mode 100644 docs/index.rst
 create mode 100644 docs/modules.rst
 create mode 100644 docs/requirements.txt

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..a1fa6ba
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,26 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - "**"
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package and docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install . -r docs/requirements.txt
+
+      - name: Build Sphinx documentation
+        run: python -m sphinx -b html docs docs/_build/html
diff --git a/.gitignore b/.gitignore
index 2d33caa..d2a5b38 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,3 +15,4 @@ __pycache__/
 
 # Documentation build
 /_build/
+/docs/_build/
diff --git a/.readthedocs.yml b/.readthedocs.yml
new file mode 100644
index 0000000..6e47ffe
--- /dev/null
+++ b/.readthedocs.yml
@@ -0,0 +1,15 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
diff --git a/README.md b/README.md
index 90042cb..bdfd2d2 100644
--- a/README.md
+++ b/README.md
@@ -27,26 +27,45 @@ Run Python commands using `uv run` to ensure the correct environment is used:
 uv run python your_script.py
 ```
 
-## Tools:
-Some of the main routines currently implemented in `pysco` :
-1. **plot**: `pysco.plot` contains custom settings for `matplotlib`([here](https://matplotlib.org/stable/)) and `corner`([here](https://corner.readthedocs.io/)). Currently, some features of `pysco.plot.corner` are available only when using the `dev` branch of my edited fork of `corner`(available [here](https://github.com/asantini29/corner.py)). In order to use another custom fork of `corner` you have to set its path as an environment variable:
+## Package structure
+The package follows a `src` layout:
+```
+pysco/
+├── src/pysco/
+│   ├── __init__.py
+│   ├── pysco.py
+│   ├── utils.py
+│   ├── eryn.py
+│   └── plots/
+│       ├── __init__.py
+│       ├── plot.py
+│       └── journals.py
+```
+
+## Tools
+Some of the main routines currently implemented in `pysco`:
+1. **plots**: `pysco.plots` contains custom settings for `matplotlib`([here](https://matplotlib.org/stable/)) and `corner`([here](https://corner.readthedocs.io/)). Currently, some features of `pysco.plots.corner` are available only when using the `dev` branch of my edited fork of `corner`(available [here](https://github.com/asantini29/corner.py)). In order to use another custom fork of `corner` you have to set its path as an environment variable:
    
    ```
    export CORNER_PATH=your-path-to-corner.py
    ```
    The module contains three different colorblind-friendly color palettes based on the results of [arXiv:2107.02270](https://arxiv.org/abs/2107.02270).
    
-3. **utils**: `pysco.utils` contains basic timing and benchmarking operations.
+2. **utils**: `pysco.utils` contains basic timing and benchmarking operations.
 
-4. **eryn**: the module `pysco.eryn` contains useful routines for the [Eryn](https://github.com/mikekatz04/Eryn) MCMC sampler. Most of the snippets currently implemented are tailored for a diagnostic plots-oriented `update_fn`.
+3. **eryn**: the module `pysco.eryn` contains useful routines for the [Eryn](https://github.com/mikekatz04/Eryn) MCMC sampler. Most of the snippets currently implemented are tailored for a diagnostic plots-oriented `update_fn`.
 
-5. **lisautils**: This module contains common samples-related operations for LISA data analysis.
+## Documentation
+Sphinx documentation is available under `docs/` and can be built locally with:
+```
+python -m sphinx -b html docs docs/_build/html
+```
 
 ## Versioning
 
 We use [SemVer](http://semver.org/) for versioning. 
 
-Current Version: 0.0.5
+Current Version: 0.0.4
 
 ## License
 
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..d9cbb0c
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,41 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../src"))
+
+project = "pysco"
+author = "Alessandro Santini"
+copyright = "2026, Alessandro Santini"
+release = "0.0.4"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+]
+
+templates_path = []
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+autodoc_mock_imports = [
+    "numpy",
+    "matplotlib",
+    "matplotlib.pyplot",
+    "matplotlib.colors",
+    "matplotlib.ticker",
+    "pandas",
+    "corner",
+    "GPUtil",
+    "chainconsumer",
+    "scipy",
+    "scipy.special",
+    "tqdm",
+    "h5py",
+    "eryn",
+    "eryn.utils",
+    "eryn.backends",
+    "eryn.moves",
+    "cycler",
+]
+
+html_theme = "sphinx_rtd_theme"
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..31cd587
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,10 @@
+pysco documentation
+===================
+
+PYthon ShortCuts & Others.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules
diff --git a/docs/modules.rst b/docs/modules.rst
new file mode 100644
index 0000000..63cc3a3
--- /dev/null
+++ b/docs/modules.rst
@@ -0,0 +1,42 @@
+API reference
+=============
+
+pysco
+-----
+
+.. automodule:: pysco
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pysco.utils
+-----------
+
+.. automodule:: pysco.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pysco.plots
+-----------
+
+.. automodule:: pysco.plots
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pysco.plots.plot
+----------------
+
+.. automodule:: pysco.plots.plot
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pysco.eryn
+----------
+
+.. automodule:: pysco.eryn
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..0ef6276
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,2 @@
+sphinx>=7
+sphinx-rtd-theme>=2

From a33434ad07a95a296a436ebbeaacb31a80b3d8b8 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 18 Mar 2026 15:24:46 +0000
Subject: [PATCH 3/4] docs: derive release version from pyproject and harden
 workflow token permissions

Co-authored-by: asantini29 <79840851+asantini29@users.noreply.github.com>
---
 .github/workflows/docs.yml | 3 +++
 docs/conf.py               | 7 ++++++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index a1fa6ba..ebfc8e3 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -5,6 +5,9 @@ on:
     branches:
       - "**"
 
+permissions:
+  contents: read
+
 jobs:
   build-docs:
     runs-on: ubuntu-latest
diff --git a/docs/conf.py b/docs/conf.py
index d9cbb0c..daa4ef8 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,12 +1,17 @@
 import os
 import sys
+from pathlib import Path
+import tomllib
 
 sys.path.insert(0, os.path.abspath("../src"))
 
 project = "pysco"
 author = "Alessandro Santini"
 copyright = "2026, Alessandro Santini"
-release = "0.0.4"
+
+pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
+with pyproject.open("rb") as f:
+    release = tomllib.load(f)["project"]["version"]
 
 extensions = [
     "sphinx.ext.autodoc",

From dbb744efdb7d0e38e31808b0116acb31fb49c09b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 18 Mar 2026 15:28:37 +0000
Subject: [PATCH 4/4] docs: document pysco.plots.journals and add GitHub Pages
 docs link

Co-authored-by: asantini29 <79840851+asantini29@users.noreply.github.com>
---
 README.md        | 1 +
 docs/modules.rst | 8 ++++++++
 2 files changed, 9 insertions(+)

diff --git a/README.md b/README.md
index bdfd2d2..2a7d833 100644
--- a/README.md
+++ b/README.md
@@ -60,6 +60,7 @@ Sphinx documentation is available under `docs/` and can be built locally with:
 ```
 python -m sphinx -b html docs docs/_build/html
 ```
+Built documentation is available on GitHub Pages: <https://asantini29.github.io/pysco/>
 
 ## Versioning
 
diff --git a/docs/modules.rst b/docs/modules.rst
index 63cc3a3..3d38d66 100644
--- a/docs/modules.rst
+++ b/docs/modules.rst
@@ -33,6 +33,14 @@ pysco.plots.plot
    :undoc-members:
    :show-inheritance:
 
+pysco.plots.journals
+--------------------
+
+.. automodule:: pysco.plots.journals
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 pysco.eryn
 ----------