Align README with src/ package layout and add automated Sphinx/RTD documentation pipeline

.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - "**"
+
+permissions:
+  contents: read
+
+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

.gitignore

@@ -15,3 +15,4 @@ __pycache__/
 
 # Documentation build
 /_build/
+/docs/_build/

.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: .

README.md

@@ -27,26 +27,46 @@ 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
+```
+Built documentation is available on GitHub Pages: <https://asantini29.github.io/pysco/>
 
 ## Versioning
 
 We use [SemVer](http://semver.org/) for versioning. 
 
-Current Version: 0.0.5
+Current Version: 0.0.4
 
 ## License
 

docs/conf.py

@@ -0,0 +1,46 @@
+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"
+
+pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
+with pyproject.open("rb") as f:
+    release = tomllib.load(f)["project"]["version"]
+
+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"

docs/index.rst

@@ -0,0 +1,10 @@
+pysco documentation
+===================
+
+PYthon ShortCuts & Others.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules

docs/modules.rst

@@ -0,0 +1,50 @@
+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.plots.journals
+--------------------
+
+.. automodule:: pysco.plots.journals
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pysco.eryn
+----------
+
+.. automodule:: pysco.eryn
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx>=7
+sphinx-rtd-theme>=2