Updated Documentation (#14)

* Updated Gitignore

* Big Documentation Update

* New doc test github action

* Update sphinx packages

* Update github action

* Another githuh action fix

Author: HKaras

.github/workflows/Build_Deploy_Docs.yml

@@ -28,6 +28,7 @@ jobs:
         run: poetry run sphinx-build -b html docsrc/ docsrc/_build/html > sphinx_build.log 2>&1
       - name: Upload build log
         uses: actions/upload-artifact@v4.6.2
+        if: always()
         with:
           name: sphinx-build-log
           path: sphinx_build.log

.github/workflows/TestBuild_Docs.yml

@@ -0,0 +1,39 @@
+name: Test Build Docs
+
+on:
+  push:
+    branches:
+      - develop
+      - main
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+      
+      - name: Install Poetry
+        run: |
+          curl -sSL https://install.python-poetry.org | python -
+          echo "${HOME}/.local/bin" >> $GITHUB_PATH
+
+      - name: Install dependencies
+        run: poetry install --with doc
+        
+      - name: Build documentation
+        run: poetry run sphinx-build -b html docsrc/ docsrc/_build/html > sphinx_build.log 2>&1
+      - name: Upload build log
+        uses: actions/upload-artifact@v4.6.2
+        if: always()
+        with:
+          name: sphinx-build-log
+          path: sphinx_build.log
+          

.gitignore

@@ -105,6 +105,7 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+.venv*
 
 # Spyder project settings
 .spyderproject
@@ -125,3 +126,7 @@ dmypy.json
 .pyre/
 
 .DS_Store
+
+poetry.lock
+
+docsrc/auto_examples/

citation.rst

@@ -0,0 +1,39 @@
+Citation
+--------
+
+Citation of scientific software is important to give credit to the developers and to help track the impact of the software in research.
+
+To cite PyEPR in publications, please currently use the Zenodo general DOI:
+
+.. image:: https://zenodo.org/badge/888368760.svg
+   :target: https://doi.org/10.5281/zenodo.17107010
+   :alt: DOI
+
+Specific PyEPR versions will also have uniquie DOIs that can be found on the respective Zenodo release page.
+The associated Zotero entry is available `here <https://doi.org/10.5281/zenodo.17107010>`_.
+
+A paper describing PyEPR is currently in preparation and will be linked here once published.
+
+Bibtex Entry
+++++++++++++
+
+.. code-block:: bibtex
+
+  @software{pyepr_2025,
+    author       = {Hugo, Karas and
+                    Jeschke, Gunnar and
+                    Stoll, Stefan},
+    title        = {JeschkeLab/PyEPR: Version 1.0},
+    month        = sep,
+    year         = 2025,
+    publisher    = {Zenodo},
+    version      = {v1.0},
+    doi          = {10.5281/zenodo.17107011},
+    url          = {https://doi.org/10.5281/zenodo.17107011},
+    swhid        = {swh:1:dir:d3ae7fdd8041eb365003ea3e40db8bbb31a6c741
+                    ;origin=https://doi.org/10.5281/zenodo.17107010;vi
+                    sit=swh:1:snp:5c1894da8cabcaf89397959130c3ff4badea
+                    5b87;anchor=swh:1:rel:316cb6fc9c055bd7058460f5559a
+                    8342d326ebd4;path=JeschkeLab-PyEPR-c194a75
+                    },
+  }

docsrc/API_docs.rst

@@ -19,6 +19,7 @@ Analysis Modules
 .. autoapisummary::
 
    pyepr.FieldSweepAnalysis
+   pyepr.HahnEchoRelaxationAnalysis
    pyepr.ResonatorProfileAnalysis
    pyepr.CarrPurcellAnalysis
    pyepr.ReptimeAnalysis
@@ -29,7 +30,7 @@ Sequences
 .. autoapisummary::
 
    pyepr.sequences.HahnEchoSequence
-   pyepr.sequences.T2RelaxationSequence
+   pyepr.sequences.HahnEchoRelaxationSequence
    pyepr.sequences.FieldSweepSequence
    pyepr.sequences.ReptimeScan
    pyepr.sequences.CarrPurcellSequence
@@ -44,7 +45,6 @@ Pulses
 
    pyepr.pulses.Pulse
    pyepr.pulses.Detection
-   pyepr.pulses.Delay
    pyepr.pulses.RectPulse
    pyepr.pulses.GaussianPulse
    pyepr.pulses.HSPulse

docsrc/README.md

@@ -0,0 +1,6 @@
+
+
+To build the documentation and serve it with live reloading, run:
+```
+sphinx-autobuild docsrc docsrc/_build/html
+```

docsrc/_static/Hardware_Interface_Diagram.svg

@@ -0,0 +1 @@
+.. include:: ../citation.rst

docsrc/citation.rst

@@ -21,13 +21,16 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = ['sphinx.ext.viewcode',
+              'sphinx_design',
+              'myst_parser',
               'sphinx.ext.intersphinx',
               'autoapi.extension',
               'sphinx_toolbox.collapse',
               'sphinx_toolbox.code',
               'sphinx_copybutton',
               'numpydoc',
-              'sphinx_favicon']
+              'sphinx_favicon',
+              'sphinx_gallery.gen_gallery']
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
@@ -44,6 +47,10 @@
 autoapi_python_use_implicit_namespaces = True
 autoapi_own_page_level = 'class'
 
+sphinx_gallery_conf = {
+     'examples_dirs': 'examples',   # path to your example scripts
+     'gallery_dirs': 'auto_examples',  # path to where to save gallery generated output
+}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output