Build docs with github actions (#235)

* deployment with tutorials

* trigger this branch

* modified lock file

* fix index file and action

* copy config files

* fix paths again

* add badge, add cache in comments (not yet implemented)

.github/workflows/build_deploy_docs.yml

@@ -0,0 +1,97 @@
+name: build and deploy docs to pages
+on:
+  # Triggers the workflow on push but only for the main branch
+  push:
+    branches: [ auto-doc-generation ]
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+  # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Maximize build space
+        uses: easimon/maximize-build-space@master
+        with:
+          root-reserve-mb: 512
+          swap-size-mb: 1024
+          remove-dotnet: 'true'
+          remove-codeql: 'true'
+          remove-android: 'true'
+          remove-docker-images: 'true'
+
+      #  Check out repo and set up Python
+      - name: Check out the repository
+        uses: actions/checkout@v4
+        with:
+          lfs: true
+
+      # Use cached python and dependencies, install poetry
+      - name: "Setup Python, Poetry and Dependencies"
+        uses: packetcoders/action-setup-cache-python-poetry@main
+        with:
+          python-version: 3.8
+          poetry-version: 1.2.2
+
+      - name: Install docs and notebook dependencies
+        run: poetry install -E notebook -E docs
+
+      - name: Install pandoc
+        run: |
+          sudo wget https://github.com/jgm/pandoc/releases/download/3.1.8/pandoc-3.1.8-1-amd64.deb
+          sudo dpkg -i pandoc-3.1.8-1-amd64.deb
+
+      - name: copy tutorial files to docs
+        run: |
+          cp -r $GITHUB_WORKSPACE/tutorial $GITHUB_WORKSPACE/docs/
+          cp -r $GITHUB_WORKSPACE/sed/config $GITHUB_WORKSPACE/docs/sed
+
+      # To be included later
+      # - name: Cache docs build
+      #   id: cache-docs
+      #   uses: actions/cache@v3
+      #   with:
+      #     path: $GITHUB_WORKSPACE/_build
+      #     key: ${{ runner.os }}-docs
+
+      - name: download WSe2 data
+        # if: steps.cache-primes.outputs.cache-hit != 'true'
+        run: |
+          cd $GITHUB_WORKSPACE/docs/tutorial
+          curl -L --output ./WSe2.zip https://zenodo.org/record/6369728/files/WSe2.zip
+          unzip -o ./WSe2.zip -d .
+
+      - name: build Sphinx docs
+        run: poetry run sphinx-build -b html $GITHUB_WORKSPACE/docs $GITHUB_WORKSPACE/_build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: '_build'
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

README.md

@@ -1,5 +1,5 @@
 # sed
-[![Documentation Status](https://readthedocs.org/projects/sed/badge/?version=latest)](https://sed.readthedocs.io/en/latest/?badge=latest)
+[![Documentation Status](https://github.com/OpenCOMPES/sed/actions/workflows/build_deploy_docs.yml/badge.svg)](https://opencompes.github.io/sed/)
 ![](https://github.com/OpenCOMPES/sed/actions/workflows/linting.yml/badge.svg?branch=main)
 ![](https://github.com/OpenCOMPES/sed/actions/workflows/testing_multiversion.yml/badge.svg?branch=main)
 ![](https://img.shields.io/pypi/pyversions/sedprocessor)

docs/conf.py

@@ -10,12 +10,14 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import tomlkit
 import os
 import sys
 sys.path.insert(0, os.path.abspath('..'))
-import tomlkit
 
 # -- Project information -----------------------------------------------------
+
+
 def _get_project_meta():
     with open('../pyproject.toml') as pyproject:
         file_contents = pyproject.read()
@@ -25,7 +27,7 @@ def _get_project_meta():
 
 pkg_meta = _get_project_meta()
 project = str(pkg_meta['name'])
-copyright = '2022, OpenCOMPES team' 
+copyright = '2022, OpenCOMPES team'
 author = 'OpenCOMPES team'
 
 # The short X.Y version
@@ -38,9 +40,11 @@ def _get_project_meta():
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx_rtd_theme','sphinx.ext.autodoc','sphinx.ext.napoleon',
-'sphinx.ext.todo','sphinx.ext.coverage','sphinx.ext.autosummary',
-'sphinx.ext.coverage','sphinx_autodoc_typehints']
+extensions = ['sphinx_rtd_theme', 'sphinx.ext.autodoc', 'sphinx.ext.napoleon',
+              'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.autosummary',
+              'sphinx.ext.coverage', 'sphinx_autodoc_typehints',     "bokeh.sphinxext.bokeh_autodoc",
+              "bokeh.sphinxext.bokeh_plot", 'nbsphinx']
+
 
 autoclass_content = 'class'
 autodoc_member_order = 'bysource'
@@ -61,7 +65,6 @@ def _get_project_meta():
 }
 
 
-
 # Set `typing.TYPE_CHECKING` to `True`:
 # https://pypi.org/project/sphinx-autodoc-typehints/
 napoleon_use_param = True
@@ -90,4 +93,4 @@ def _get_project_meta():
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['_static']

docs/index.rst

@@ -21,9 +21,9 @@ Single-Event DataFrame (SED) documentation
    :numbered:
    :caption: Examples
 
-   tutorial/1_binning_fake_data
-   tutorial/2_conversion_pipeline_for_example_time-resolved_ARPES_data
-   tutorial/3_metadata_collection_and_export_to_NeXus
+   tutorial/1_binning_fake_data.ipynb
+   tutorial/2_conversion_pipeline_for_example_time-resolved_ARPES_data.ipynb
+   tutorial/3_metadata_collection_and_export_to_NeXus.ipynb
 
 .. toctree::
    :maxdepth: 2