added documantation

Author: Peter Braun

.gitignore

@@ -9,3 +9,5 @@ dist
 pid
 logs
 .secop-ophyd
+
+_api

README.md

@@ -2,22 +2,24 @@
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![PyPI](https://img.shields.io/pypi/v/secop-ophyd.svg)](https://pypi.org/project/secop-ophyd)
 
-# secop-ophyd
-
-This package allows seamless itegration of hardware that provides a SECoP interface into bluesky.
+# SECoP-Ophyd
 
+**SECoP-Ophyd** enables seamless integration of SECoP (Sample Environment Communication Protocol) devices into the  Bluesky experiment orchestration framework.
 
 ![secop-ophyd-arch](https://github.com/user-attachments/assets/cd82cfbe-68dc-4b3c-b872-5b1b7c7db82a)
 
+## Documentation
 
+|    Resource     |     Link                                                     |
+| :-------------: | :----------------------------------------------------------: |
+| Documentation   | <https://sampleenvironment.github.io/secop-ophyd/>           |
+| Demo Repository | <https://codebase.helmholtz.cloud/rock-it-secop/secop-sim>   |
+| PyPI            | <https://pypi.org/project/secop-ophyd>                       |
+| Issue Tracker   | <https://github.com/SampleEnvironment/secop-ophyd/issues>    |
 
-## Getting Started
-A demo repository that shows the full functionality of the integration is provided here:
-
-[secop-sim](https://codebase.helmholtz.cloud/rock-it-secop/secop-sim)
-
-
-## Further information:
+## Further Information
 
-#### SECoP (https://github.com/SampleEnvironment/SECoP)
-#### Frappy (https://github.com/SampleEnvironment/frappy)
+- [SECoP Specification](https://sampleenvironment.github.io/secop-site/)
+- [Frappy (Framework for implementing SEC nodes)](https://github.com/SampleEnvironment/frappy)
+- [Ophyd-async Documentation](https://blueskyproject.io/ophyd-async/main/index.html)
+- [Bluesky Project](https://blueskyproject.io/)

docs/images/favicon.ico

@@ -0,0 +1,4 @@
+/* Allow a wider screen so we can fit 88 chars of source code on it */
+.bd-page-width {
+    max-width: 100rem;  /* default is 88rem */
+}

docs/images/logo.svg

@@ -3,64 +3,142 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import secop_ophyd
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+project = "SECoP-Ophyd"
+copyright = "2024, Peter Braun"
+author = "Peter Braun"
+release = secop_ophyd.__version__
+
+# Clean up version for display - extract just X.Y.Z from version strings like "0.13.9.dev0+gb43270d29.d20251029"
+if "+" in secop_ophyd.__version__:
+    # Development version - use short version or "dev"
+    release = secop_ophyd.__version__.split("+")[0]
+else:
+    release = secop_ophyd.__version__
+
+version = secop_ophyd.__version__
+
+language = "en"
+
+source_suffix = ".rst"
+master_doc = "index"
+
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
-    "sphinx.ext.githubpages",
+    # for diagrams
+    "sphinxcontrib.mermaid",
+    # Use this for generating API docs
+    "autodoc2",
+    # For linking to external sphinx documentation
     "sphinx.ext.intersphinx",
-    "sphinx.ext.mathjax",
+    # Add links to source code in API docs
     "sphinx.ext.viewcode",
+    # Add a copy button to each code block
+    "sphinx_copybutton",
+    # For the card element
+    "sphinx_design",
+    # To make .nojekyll
+    "sphinx.ext.githubpages",
+    # To make the {ipython} directive
     "IPython.sphinxext.ipython_directive",
+    # To syntax highlight "ipython" language code blocks
     "IPython.sphinxext.ipython_console_highlighting",
+    # To embed matplotlib plots generated from code
     "matplotlib.sphinxext.plot_directive",
-    "numpydoc",
-    "sphinx_click",
-    "sphinx_copybutton",
+    # To parse markdown
     "myst_parser",
-    "sphinxcontrib.jquery",
-    "sphinxcontrib.mermaid",
 ]
 
 templates_path = ["_templates"]
 exclude_patterns = []  # type: ignore
 
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "alabaster"
-html_static_path = ["_static"]
+# Which package to load and document
+autodoc2_packages = [{"path": "../../src/secop_ophyd", "auto_mode": True}]
 
+# Put them in docs/_api which is git ignored
+autodoc2_output_dir = "_api"
 
-# Generate the API documentation when building
-autosummary_generate = True
-numpydoc_show_class_members = False
 
-source_suffix = ".rst"
+# Don't document private things
+autodoc2_hidden_objects = {"private", "dunder", "inherited"}
 
-master_doc = "index"
+# MyST parser extensions
+myst_enable_extensions = ["colon_fence", "fieldlist"]
 
-import secop_ophyd
+# Intersphinx configuration for linking to external documentation
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "bluesky": ("https://blueskyproject.io/bluesky/main", None),
+    "ophyd-async": ("https://blueskyproject.io/ophyd-async/main", None),
+    "numpy": ("https://numpy.org/devdocs/", None),
+}
 
-project = "SECoP-Ophyd"
-copyright = "2024, Peter Braun"
-author = "Peter Braun"
-release = secop_ophyd.__version__
-version = secop_ophyd.__version__
+# Set copy-button to ignore python and bash prompts
+copybutton_prompt_text = (
+    r">>> |\\.\\.\\. |\\$ |In \\[\\d*\\]: | {2,5}\\.\\.\\.: | {5,8}: "
+)
+copybutton_prompt_is_regexp = True
 
-language = "en"
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+# Generate the API documentation when building
+autosummary_generate = True
+numpydoc_show_class_members = False
 
 
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
-import sphinx_rtd_theme
+html_theme = "pydata_sphinx_theme"
+
+# Theme options for pydata_sphinx_theme
+html_theme_options = {
+    "use_edit_page_button": True,
+    "github_url": "https://github.com/SampleEnvironment/secop-ophyd",
+    "icon_links": [
+        {
+            "name": "PyPI",
+            "url": "https://pypi.org/project/secop-ophyd",
+            "icon": "fas fa-cube",
+        },
+    ],
+    "external_links": [
+        {
+            "name": "SECoP Specification",
+            "url": "https://sampleenvironment.github.io/secop-site/",
+        },
+    ],
+    "navigation_with_keys": False,
+    "show_toc_level": 3,
+}
+
+html_logo = "../images/logo.svg"
+html_favicon = "../images/favicon.ico"
+
+html_context = {
+    "github_user": "SampleEnvironment",
+    "github_repo": "secop-ophyd",
+    "github_version": "main",
+    "doc_path": "docs",
+}
+
+# If true, "Created using Sphinx" is shown in the HTML footer.
+html_show_sphinx = False
+
+# If true, "(C) Copyright ..." is shown in the HTML footer.
+html_show_copyright = False
+
+# Custom CSS
+html_css_files = ["custom.css"]