Add API documentation

.copier-answers.yml

@@ -0,0 +1,9 @@
+# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
+_commit: 0.1.0
+_src_path: https://github.com/python-accelerator-middle-layer/pyaml-repository-template.git
+distribution_name: tango-pyaml
+html_title: tango-pyaml
+import_name: tango.pyaml
+package_name: tango-pyaml
+repository_url: https://github.com/python-accelerator-middle-layer/tango-pyaml
+use_docs_extra: false

.readthedocs.yaml

@@ -0,0 +1,25 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+      extra_requirements: []

README.md

@@ -1,14 +1,13 @@
 # tango-pyaml
 
-**Bridge between **[**Tango Controls**](https://www.tango-controls.org/)** and PyAML**
-
+**Bridge between **[**Tango Controls**](https://www.tango-controls.org/)** and pyAML**
 
+[![Documentation Status](https://readthedocs.org/projects/tango-pyaml/badge/?version=latest)](https://tango-pyaml.readthedocs.io/en/latest/?badge=latest)
+[![Current release](https://img.shields.io/github/v/release/python-accelerator-middle-layer/tango-pyaml)](https://github.com/python-accelerator-middle-layer/tango-pyaml/releases)
 
 ## Overview
 
-`tango-pyaml` is a Python bridge between the [Tango control system](https://www.tango-controls.org/) and the [PyAML](https://github.com/python-accelerator-middle-layer/pyaml) abstraction layer for control systems. It provides a set of classes that allow Tango attributes and devices to be accessed and controlled using PyAML concepts.
-
-This library is part of the **Python Accelerator Middle Layer (PyAML)** ecosystem.
+`tango-pyaml` is a Python bridge between the [Tango control system](https://www.tango-controls.org/) and the [pyAML](https://github.com/python-accelerator-middle-layer/pyaml) abstraction layer for control systems. It provides a set of classes that allow Tango attributes and devices to be accessed and controlled using pyAML concepts.
 
 ## Features
 
@@ -21,79 +20,38 @@ This library is part of the **Python Accelerator Middle Layer (PyAML)** ecosyste
 
 ## Installation
 
+Install the package from PyPI:
+
 ```bash
 pip install tango-pyaml
 ```
 
-## Requirements
+## Development
 
-- Python >= 3.9
-- [PyTango](https://pytango.readthedocs.io/en/latest/) >= 9.5.1
-- [PyAML](https://github.com/python-accelerator-middle-layer/pyaml)
-- [pydantic](https://docs.pydantic.dev/) >= 2.0
-
-For development and testing:
+Install the development dependencies with:
 
 ```bash
 pip install tango-pyaml[dev]
 ```
 
-## Usage Example
-
-This is an example of an explicit call to a Tango attribute using PyAML. For more details about implicit declaration and broader configuration options, please refer to the [PyAML documentation](https://github.com/python-accelerator-middle-layer/pyaml).
-
-Configuration file `attribute.yaml`:
-
-```yaml
-attribute: "sys/tg_test/1/float_scalar"
-unit: "A"
-```
-
-Python code:
-
-```python
-from tango.pyaml.attribute import Attribute
-import yaml
+Run the test suite with:
 
-with open("attribute.yaml") as f:
-    cfg_dict = yaml.safe_load(f)
-
-attr = Attribute(**cfg_dict)
-
-attr.set(10.0)
-value = attr.get()
-readback = attr.readback()
-
-print(f"Value: {value}, Readback: {readback.value} [{readback.quality}]")
+```bash
+pytest
 ```
 
-## Available Classes
-
-- `Attribute` — Read/write access to a Tango attribute
-- `AttributeReadOnly` — Read-only attribute wrapper
-- `AttributeList` — Manage a group of attributes from multiple devices
-- `TangoControlSystem` — Adapter to configure global Tango control system context
-
-## Testing
-
-Tests rely on mocked Tango devices and attributes using `unittest.mock`. To run tests:
+Install the pre-commit hooks with:
 
 ```bash
-pytest
+pre-commit install
 ```
 
-## Project Structure
-
-- `tango.pyaml.attribute` – Main attribute interface
-- `tango.pyaml.attribute_read_only` – Read-only attribute implementation
-- `tango.pyaml.attribute_list` – Attribute groups with `tango.Group`
-- `tango.pyaml.tango_attribute` – Base class wrapping attribute logic
-- `mocked_device_proxy.py` – In-memory mock for Tango `DeviceProxy` and `AttributeProxy`
+## Documentation
 
-## License
+The documentation is available at:
 
-This project is licensed under the MIT License.
+<https://tango-pyaml.readthedocs.io/en/stable/>
 
-## Links
+## Contributing
 
-- 🧺 [Repository](https://github.com/python-accelerator-middle-layer/tango-pyaml)
+Please use the issue tracker or submit a pull request.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx~= 8.1
+pydata-sphinx-theme
+myst_parser
+sphinx-copybutton

docs/source/_static/custom.css

@@ -0,0 +1,7 @@
+.api-root h1 {
+    display: none;
+}
+
+.api-generation {
+    display: none;
+}

docs/source/api.rst

@@ -0,0 +1,14 @@
+API Reference
+=============
+
+.. container:: api-generation
+
+   .. autosummary::
+      :toctree: api
+      :recursive:
+
+      tango.pyaml
+
+.. container:: api-root
+
+   .. include:: api/tango.pyaml.rst

docs/source/conf.py

@@ -0,0 +1,77 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "tango-pyaml"
+copyright = "2026, pyAML Collaboration"
+author = "pyAML Collaboration"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "myst_parser",
+    "sphinx_copybutton",
+]
+
+autosummary_generate = True
+
+# Maybe add "undoc-members": True here later
+autodoc_default_options = {
+    "members": True,
+    "show-inheritance": True,
+    "member-order": "groupwise",
+}
+
+autodoc_typehints = "description"
+autodoc_typehints_description_target = "documented"
+autodoc_typehints_format = "short"
+# autosummary_generate_overwrite = False
+# autosummary_ignore_module_all = False
+autoclass_content = "both"  # include both class docstring and __init__
+
+napoleon_use_rtype = False  # More legible
+# napoleon_numpy_docstring = False  # Force consistency, leave only Google
+# napoleon_custom_sections = [("Returns", "params_style")]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "pydata_sphinx_theme"
+html_static_path = ["_static"]
+html_title = "tango-pyaml"
+html_show_sourcelink = False
+html_css_files = ["custom.css"]
+html_logo = "_static/_images/logo.png"
+
+html_theme_options = {
+    "navigation_depth": 4,
+    "show_nav_level": 2,
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/python-accelerator-middle-layer/tango-pyaml",
+            "icon": "fa-brands fa-github",
+            "type": "fontawesome",
+        },
+    ],
+}
+
+html_sidebars = {
+    "**": [
+        "sidebar-collapse",
+        "sidebar-nav-bs",
+    ],
+}

docs/source/index.rst

@@ -0,0 +1,16 @@
+
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
+
+.. seealso::
+
+   This package is part of the
+   `pyAML ecosystem <https://python-accelerator-middle-layer.github.io/>`__.
+   See the `main pyAML documentation
+   <https://python-accelerator-middle-layer.github.io/documentation/>`__
+   for tutorials, how-to guides, and an overview of the ecosystem.
+
+.. toctree::
+   :hidden:
+
+   api

pyproject.toml

@@ -54,6 +54,7 @@ dev = [
     "mypy",                 # Typage statique (optionnel)
     "ipython",              # Débogage interactif
     "pre-commit",
+    "copier",
 ]
 
 [project.entry-points."pyaml.schemas"]