Documnetation

.dist/fluxie-docs/.readthedocs.yaml

@@ -0,0 +1,25 @@
+# .readthedocs.yaml
+#
+# Read the Docs build configuration.
+# Reference: https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    # Install fluxie itself so autodoc can import the package during the build.
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+    # Install the pinned documentation dependencies separately to ensure
+    # reproducible builds regardless of what gets released on PyPI.
+    - requirements: docs/requirements.txt

.dist/fluxie-docs/DOCS_README.md

@@ -0,0 +1,69 @@
+# fluxie — Sphinx documentation
+
+This directory contains the source files for the fluxie Sphinx documentation,
+hosted at https://fluxie.readthedocs.io.
+
+## Directory layout
+
+```
+docs/
+├── conf.py                 Sphinx configuration
+├── index.rst               Root table of contents
+├── getting_started.rst     Installation and quick-start guide
+├── data_format.rst         Input file formats and naming conventions
+├── requirements.txt        Pinned build dependencies for Read the Docs
+├── api/
+│   └── index.rst           Auto-generated API reference entry point
+├── developer/
+│   └── index.rst           Developer guide (setup, tests, contributing)
+├── tutorials/
+│   ├── index.rst           Tutorial listing
+│   └── example_basics.nblink  Links to scripts/example_basics.ipynb
+└── _static/                Custom CSS / images (add as needed)
+
+.readthedocs.yaml           Read the Docs build configuration (repo root)
+pyproject_docs_addition.toml  Snippet to add to pyproject.toml
+```
+
+## Building locally
+
+1. Install the documentation dependencies:
+
+   ```bash
+   pip install -e ".[docs]"
+   ```
+
+2. Build the HTML output:
+
+   ```bash
+   cd docs
+   make html
+   ```
+
+3. Open `docs/_build/html/index.html` in a browser.
+
+To rebuild from scratch:
+
+```bash
+make clean html
+```
+
+## Connecting to Read the Docs
+
+1. Sign in to https://readthedocs.org with the openghg GitHub account.
+2. Click **Import a project** and select `openghg/fluxie`.
+3. Read the Docs detects `.readthedocs.yaml` automatically and uses it for all
+   subsequent builds.
+4. Every push to `devel` triggers a new build.  Git tags (e.g. `v2.1`) appear
+   as versioned documentation snapshots.
+
+## Adding content
+
+- **New page:** Create a `.rst` (or `.md`) file in the appropriate
+  subdirectory and add its name to the nearest `toctree` directive.
+- **New tutorial notebook:** Add the notebook to `scripts/`, create a
+  matching `.nblink` stub in `docs/tutorials/`, and add the name to the
+  `toctree` in `docs/tutorials/index.rst`.
+- **API coverage:** The API reference is built from docstrings.  Any public
+  function or class that lacks a docstring will appear as an empty entry.
+  Write NumPy-style docstrings to populate it.

.dist/fluxie-docs/docs/_static/.gitkeep

@@ -0,0 +1,2 @@
+# This file exists only to ensure the _static/ directory is tracked by git.
+# Place any custom CSS, images, or JavaScript files here.

.dist/fluxie-docs/docs/api/index.rst

@@ -0,0 +1,14 @@
+API reference
+=============
+
+This section is generated automatically from the source code.
+All public symbols in the ``fluxie`` package are listed here together with
+their docstrings and type signatures.
+
+Click the ``[source]`` link next to any symbol to view its implementation.
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+
+   fluxie

.dist/fluxie-docs/docs/conf.py

@@ -0,0 +1,81 @@
+# docs/conf.py
+#
+# Sphinx configuration for the fluxie documentation.
+# Build locally:  cd docs && make html
+# Hosted on:      https://fluxie.readthedocs.io
+
+import os
+import sys
+
+# Make the fluxie package importable during the build so autodoc can inspect it.
+sys.path.insert(0, os.path.abspath(".."))
+
+# ---------------------------------------------------------------------------
+# Project information
+# ---------------------------------------------------------------------------
+
+project = "fluxie"
+copyright = "2024, OpenGHG contributors"
+author = "OpenGHG contributors"
+
+# Pull the version from the installed package so it stays in sync automatically.
+try:
+    from importlib.metadata import version as _pkg_version
+    release = _pkg_version("fluxie")
+except Exception:
+    release = "unknown"
+
+version = ".".join(release.split(".")[:2])
+
+# General configuration
+
+
+extensions = [
+    "sphinx.ext.autodoc",           # Extract docstrings from source code
+    "sphinx.ext.autosummary",       # Generate summary tables for modules/classes
+    "sphinx.ext.napoleon",          # Parse NumPy- and Google-style docstrings
+    "sphinx.ext.viewcode",          # Add [source] links next to each symbol
+    "sphinx.ext.intersphinx",       # Cross-link to NumPy, xarray, pandas, etc.
+    "sphinx_autodoc_typehints",     # Render type hints in the signature line
+    "myst_parser",                  # Allow Markdown (.md) source files
+    "nbsphinx",                     # Render Jupyter notebooks
+]
+
+autosummary_generate = True
+
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": False,
+    "show-inheritance": True,
+    "member-order": "bysource",
+}
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_param = True
+napoleon_use_rtype = True
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy":  ("https://numpy.org/doc/stable", None),
+    "xarray": ("https://docs.xarray.dev/en/stable", None),
+    "pandas": ("https://pandas.pydata.org/docs", None),
+}
+
+templates_path    = ["_templates"]
+exclude_patterns  = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"]
+
+
+
+html_theme = "sphinx_rtd_theme"
+
+html_theme_options = {
+    "navigation_depth": 4,
+    "collapse_navigation": False,
+    "sticky_navigation": True,
+    "titles_only": False,
+}
+
+html_static_path = ["_static"]
+
+nbsphinx_execute = "never"