add github actions workflow for building and deploying docs

Author: peterhcharlton

.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Build and deploy docs
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+          
+      - name: Generate API docs
+        run: |
+          sphinx-apidoc -f -o docs/source/api src/longitudinal_ecg_analysis
+         
+      - name: Build Sphinx docs
+        run: |
+          sphinx-build -W -b html docs/source docs/build/html
+          
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/html
+
+      - name: Deploy to GitHub Pages
+        if: github.ref == 'refs/heads/main'
+        uses: actions/deploy-pages@v4
+           

.gitignore

@@ -1,4 +1,5 @@
 .DS_Store
 venv/
 __pycache__/
-*.py[cod]
+*.py[cod]
+docs/build/

docs/build/html/_sources/index.rst.txt

@@ -65,5 +65,5 @@ Further details of this example are provided in the :ref:`Running demo analysis
    examples
    variables
    maintenance
-   API Documentation <modules>
+   API Documentation <api/modules>
 

docs/build/html/_sources/maintenance.rst.txt

@@ -23,7 +23,7 @@ The documentation is a mixture of manually written pages, and auto-generated API
 * Update the auto-generated API documentation using::
    
    cd longitudinal-ecg-analysis/
-   sphinx-apidoc -f -o docs/source ./src/longitudinal_ecg_analysis
+   sphinx-apidoc -f -o docs/source/api ./src/longitudinal_ecg_analysis
    cd docs
    make html
    cd ..

docs/build/html/datasets.html

@@ -53,7 +53,7 @@
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="variables.html">Variables</a></li>
 <li class="toctree-l1"><a class="reference internal" href="maintenance.html">Maintenance</a></li>
-<li class="toctree-l1"><a class="reference internal" href="modules.html">API Documentation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api/modules.html">API Documentation</a></li>
 </ul>
 
         </div>

docs/build/html/examples.html

@@ -91,7 +91,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="variables.html">Variables</a></li>
 <li class="toctree-l1"><a class="reference internal" href="maintenance.html">Maintenance</a></li>
-<li class="toctree-l1"><a class="reference internal" href="modules.html">API Documentation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api/modules.html">API Documentation</a></li>
 </ul>
 
         </div>

docs/build/html/genindex.html

@@ -48,7 +48,7 @@
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="variables.html">Variables</a></li>
 <li class="toctree-l1"><a class="reference internal" href="maintenance.html">Maintenance</a></li>
-<li class="toctree-l1"><a class="reference internal" href="modules.html">API Documentation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api/modules.html">API Documentation</a></li>
 </ul>
 
         </div>
@@ -131,7 +131,7 @@ <h2>Installation<a class="headerlink" href="#installation" title="Link to this h
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="variables.html">Variables</a></li>
 <li class="toctree-l1"><a class="reference internal" href="maintenance.html">Maintenance</a></li>
-<li class="toctree-l1"><a class="reference internal" href="modules.html">API Documentation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="api/modules.html">API Documentation</a></li>
 </ul>
 </div>
 </section>

docs/build/html/index.html

@@ -18,9 +18,7 @@
       <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/js/theme.js"></script>
     <link rel="index" title="Index" href="genindex.html" />
-    <link rel="search" title="Search" href="search.html" />
-    <link rel="next" title="longitudinal_ecg_analysis.feature_extractors package" href="longitudinal_ecg_analysis.feature_extractors.html" />
-    <link rel="prev" title="longitudinal_ecg_analysis package" href="longitudinal_ecg_analysis.html" /> 
+    <link rel="search" title="Search" href="search.html" /> 
 </head>
 
 <body class="wy-body-for-nav"> 
@@ -43,34 +41,13 @@
 </div>
         </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
               <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
-<ul class="current">
+<ul>
 <li class="toctree-l1"><a class="reference internal" href="overview.html">Overview</a></li>
 <li class="toctree-l1"><a class="reference internal" href="datasets.html">Datasets</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="variables.html">Variables</a></li>
 <li class="toctree-l1"><a class="reference internal" href="maintenance.html">Maintenance</a></li>
-<li class="toctree-l1 current"><a class="reference internal" href="modules.html">API Documentation</a><ul class="current">
-<li class="toctree-l2 current"><a class="reference internal" href="longitudinal_ecg_analysis.html">longitudinal_ecg_analysis package</a><ul class="current">
-<li class="toctree-l3 current"><a class="reference internal" href="longitudinal_ecg_analysis.html#subpackages">Subpackages</a><ul class="current">
-<li class="toctree-l4 current"><a class="current reference internal" href="#">longitudinal_ecg_analysis.dataset_curators package</a></li>
-<li class="toctree-l4"><a class="reference internal" href="longitudinal_ecg_analysis.feature_extractors.html">longitudinal_ecg_analysis.feature_extractors package</a></li>
-</ul>
-</li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#submodules">Submodules</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.compile_for_stats">longitudinal_ecg_analysis.compile_for_stats module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.curate_analysis_dataset">longitudinal_ecg_analysis.curate_analysis_dataset module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#longitudinal-ecg-analysis-curate-entire-dataset-module">longitudinal_ecg_analysis.curate_entire_dataset module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.derive_signal_features">longitudinal_ecg_analysis.derive_signal_features module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.gen_analysis_settings">longitudinal_ecg_analysis.gen_analysis_settings module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.gen_dataset_settings">longitudinal_ecg_analysis.gen_dataset_settings module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.run_demo">longitudinal_ecg_analysis.run_demo module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.stats_analysis">longitudinal_ecg_analysis.stats_analysis module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.utils">longitudinal_ecg_analysis.utils module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis">Module contents</a></li>
-</ul>
-</li>
-</ul>
-</li>
+<li class="toctree-l1"><a class="reference internal" href="api/modules.html">API Documentation</a></li>
 </ul>
 
         </div>
@@ -87,8 +64,6 @@
           <div role="navigation" aria-label="Page navigation">
   <ul class="wy-breadcrumbs">
       <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
-          <li class="breadcrumb-item"><a href="modules.html">longitudinal_ecg_analysis</a></li>
-          <li class="breadcrumb-item"><a href="longitudinal_ecg_analysis.html">longitudinal_ecg_analysis package</a></li>
       <li class="breadcrumb-item active">longitudinal_ecg_analysis.dataset_curators package</li>
       <li class="wy-breadcrumbs-aside">
             <a href="_sources/longitudinal_ecg_analysis.dataset_curators.rst.txt" rel="nofollow"> View page source</a>
@@ -308,10 +283,7 @@ <h2>Submodules<a class="headerlink" href="#submodules" title="Link to this headi
 
            </div>
           </div>
-          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
-        <a href="longitudinal_ecg_analysis.html" class="btn btn-neutral float-left" title="longitudinal_ecg_analysis package" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
-        <a href="longitudinal_ecg_analysis.feature_extractors.html" class="btn btn-neutral float-right" title="longitudinal_ecg_analysis.feature_extractors package" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
-    </div>
+          <footer>
 
   <hr/>
 

docs/build/html/longitudinal_ecg_analysis.dataset_curators.html

@@ -18,8 +18,7 @@
       <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/js/theme.js"></script>
     <link rel="index" title="Index" href="genindex.html" />
-    <link rel="search" title="Search" href="search.html" />
-    <link rel="prev" title="longitudinal_ecg_analysis.dataset_curators package" href="longitudinal_ecg_analysis.dataset_curators.html" /> 
+    <link rel="search" title="Search" href="search.html" /> 
 </head>
 
 <body class="wy-body-for-nav"> 
@@ -42,34 +41,13 @@
 </div>
         </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
               <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
-<ul class="current">
+<ul>
 <li class="toctree-l1"><a class="reference internal" href="overview.html">Overview</a></li>
 <li class="toctree-l1"><a class="reference internal" href="datasets.html">Datasets</a></li>
 <li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
 <li class="toctree-l1"><a class="reference internal" href="variables.html">Variables</a></li>
 <li class="toctree-l1"><a class="reference internal" href="maintenance.html">Maintenance</a></li>
-<li class="toctree-l1 current"><a class="reference internal" href="modules.html">API Documentation</a><ul class="current">
-<li class="toctree-l2 current"><a class="reference internal" href="longitudinal_ecg_analysis.html">longitudinal_ecg_analysis package</a><ul class="current">
-<li class="toctree-l3 current"><a class="reference internal" href="longitudinal_ecg_analysis.html#subpackages">Subpackages</a><ul class="current">
-<li class="toctree-l4"><a class="reference internal" href="longitudinal_ecg_analysis.dataset_curators.html">longitudinal_ecg_analysis.dataset_curators package</a></li>
-<li class="toctree-l4 current"><a class="current reference internal" href="#">longitudinal_ecg_analysis.feature_extractors package</a></li>
-</ul>
-</li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#submodules">Submodules</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.compile_for_stats">longitudinal_ecg_analysis.compile_for_stats module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.curate_analysis_dataset">longitudinal_ecg_analysis.curate_analysis_dataset module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#longitudinal-ecg-analysis-curate-entire-dataset-module">longitudinal_ecg_analysis.curate_entire_dataset module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.derive_signal_features">longitudinal_ecg_analysis.derive_signal_features module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.gen_analysis_settings">longitudinal_ecg_analysis.gen_analysis_settings module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.gen_dataset_settings">longitudinal_ecg_analysis.gen_dataset_settings module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.run_demo">longitudinal_ecg_analysis.run_demo module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.stats_analysis">longitudinal_ecg_analysis.stats_analysis module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis.utils">longitudinal_ecg_analysis.utils module</a></li>
-<li class="toctree-l3"><a class="reference internal" href="longitudinal_ecg_analysis.html#module-longitudinal_ecg_analysis">Module contents</a></li>
-</ul>
-</li>
-</ul>
-</li>
+<li class="toctree-l1"><a class="reference internal" href="api/modules.html">API Documentation</a></li>
 </ul>
 
         </div>
@@ -86,8 +64,6 @@
           <div role="navigation" aria-label="Page navigation">
   <ul class="wy-breadcrumbs">
       <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
-          <li class="breadcrumb-item"><a href="modules.html">longitudinal_ecg_analysis</a></li>
-          <li class="breadcrumb-item"><a href="longitudinal_ecg_analysis.html">longitudinal_ecg_analysis package</a></li>
       <li class="breadcrumb-item active">longitudinal_ecg_analysis.feature_extractors package</li>
       <li class="wy-breadcrumbs-aside">
             <a href="_sources/longitudinal_ecg_analysis.feature_extractors.rst.txt" rel="nofollow"> View page source</a>
@@ -165,9 +141,7 @@ <h2>Submodules<a class="headerlink" href="#submodules" title="Link to this headi
 
            </div>
           </div>
-          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
-        <a href="longitudinal_ecg_analysis.dataset_curators.html" class="btn btn-neutral float-left" title="longitudinal_ecg_analysis.dataset_curators package" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
-    </div>
+          <footer>
 
   <hr/>