Sphinx docs (#45)

* pages cicd

* pages publish correct permissions

* pages publish split into two jobs

* cicd fix: removed uneccecary deploy step

* only deploy pages on master branch updates

---------

Co-authored-by: Peter Braun <[email protected]>

Author: Bilchreis

.github/workflows/code.yaml

@@ -54,6 +54,64 @@ jobs:
       run: |
         uv run pytest tests/ -v
 
+  build-pages:
+    if: github.ref == 'refs/heads/master'
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    runs-on: ubuntu-latest
+
+
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+      fail-fast: false
+
+    steps:
+
+    - name: Set env.REPOSITORY_NAME  # just the repo, as opposed to org/repo
+      shell: bash -l {0}
+      run: |
+        export REPOSITORY_NAME=${GITHUB_REPOSITORY#*/}
+        echo "REPOSITORY_NAME=${REPOSITORY_NAME}" >> $GITHUB_ENV
+
+    - uses: actions/checkout@v4
+
+    - name: Install uv and set the python version
+      uses: astral-sh/setup-uv@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install secop-ophyd with all deps
+      run: uv sync --all-extras
+
+    - name: Build Docs
+      shell: bash -l {0}
+      run: uv run make -C docs/ html
+
+    - name: Upload
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: ./docs/build/html
+
+  # Deployment job
+  deploy-pages:
+    if: github.ref == 'refs/heads/master'
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build-pages
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
 
   build:
     name: Build distribution 📦

.pre-commit-config.yaml

@@ -15,6 +15,7 @@ repos:
     rev: 6.1.0
     hooks:
       - id: flake8
+        exclude: ^docs/
 
   - repo: https://github.com/PyCQA/isort
     rev: 6.0.1
@@ -36,4 +37,4 @@ repos:
     hooks:
     -   id: mypy
         args: [--config-file=.mypy.ini]
-        exclude: ^cfg/
+        exclude: ^(cfg/|docs/)

docs/source/conf.py

@@ -6,18 +6,26 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = "SECoP-Ophyd"
-copyright = "2024, Peter Wegmann"
-author = "Peter Wegmann"
-release = "0.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    "sphinx.ext.duration",
-    "sphinx.ext.doctest",
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "IPython.sphinxext.ipython_directive",
+    "IPython.sphinxext.ipython_console_highlighting",
+    "matplotlib.sphinxext.plot_directive",
+    "numpydoc",
+    "sphinx_click",
+    "sphinx_copybutton",
+    "myst_parser",
+    "sphinxcontrib.jquery",
+    "sphinxcontrib.mermaid",
 ]
 
 templates_path = ["_templates"]
@@ -28,3 +36,31 @@
 
 html_theme = "alabaster"
 html_static_path = ["_static"]
+
+
+# Generate the API documentation when building
+autosummary_generate = True
+numpydoc_show_class_members = False
+
+source_suffix = ".rst"
+
+master_doc = "index"
+
+import secop_ophyd
+
+project = "SECoP-Ophyd"
+copyright = "2024, Peter Braun"
+author = "Peter Braun"
+release = secop_ophyd.__version__
+version = secop_ophyd.__version__
+
+language = "en"
+
+
+# -- 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

pyproject.toml

@@ -40,7 +40,13 @@ dev = [
     'mlzlog',
     'python-dotenv',
     'bluesky',
-    'sphinx',
+    "sphinx !=4.1.0, !=4.1.1, !=4.1.2, !=4.2.0",
+    "sphinx-click",
+    "sphinx-copybutton",
+    "sphinx_rtd_theme",
+    "sphinxcontrib-mermaid",
+    "myst-parser",
+    "numpydoc",
     'snakefmt'
 ]
 

src/secop_ophyd/__init__.py

@@ -0,0 +1,6 @@
+from ._version import __version__, __version_tuple__
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+]