Actions docs (#194)

* added actions workflow for docs * ammaraskar sphinx syntax error * ammaraskar sphinx syntax error, trying actions v1 * docs syntax error * docs syntax error * docs syntax error * docs syntax error * docs syntax error * removed dash * install theme * install theme * trying peaceiris instead * trying peaceiris instead * trying peaceiris instead * trying peaceiris instead * trying peaceiris instead * adding nojekyll file * added make run * installing requirements * adding python version * adding python version * adding python version * changing branch * added redirect index * added permalink * updated actions branch, added permalink to index * removed build binaries * changed workflow branch to gh-pages * added into in index.rst file * testing github.ref in actions * added intro in index * changed publish dir to avoid jekyll build * changed publish dir * added index in docs root * changed to main branch * trying without publish dir * changed action to push on main * added to readme * fixed spelling in index rst * fixed spelling in index rst * fixed spelling in index rst * changed publish dir * changed publish dir * temporarily changed github ref * adding back publish dir * updated index.rst * changed docs workflow to only run when theres a push to main * final revert back to main after testing * text formatting for consistency * testing newer actions versions * reverting back to main branch Co-authored-by: Ziwen Liu <[email protected]>
mehta-lab · Jan 10, 2023 · 0420d46 · 0420d46
1 parent 91da099
commit 0420d46
Show file tree

Hide file tree

Showing 25 changed files with 81 additions and 19 deletions.
diff --git a/.github/workflows/actions_docs.yml b/.github/workflows/actions_docs.yml
@@ -0,0 +1,31 @@
+name: sphinx
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.7
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install sphinx sphinx_rtd_theme
+          pip install -r requirements.txt
+      - name: Sphinx build
+        run: |
+          make -C docs/ html
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/
+          force_orphan: true
diff --git a/.github/workflows/actions_testing.yml b/.github/workflows/actions_testing.yml
@@ -11,10 +11,10 @@ jobs:
 
     steps:
     - name: Checkout repo
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
 

diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/build/doctrees/environment.pickle b/docs/build/doctrees/environment.pickle
diff --git a/docs/build/doctrees/index.doctree b/docs/build/doctrees/index.doctree
diff --git a/docs/build/doctrees/micro_dl.cli.doctree b/docs/build/doctrees/micro_dl.cli.doctree
diff --git a/docs/build/doctrees/micro_dl.doctree b/docs/build/doctrees/micro_dl.doctree
diff --git a/docs/build/doctrees/micro_dl.inference.doctree b/docs/build/doctrees/micro_dl.inference.doctree
diff --git a/docs/build/doctrees/micro_dl.input.doctree b/docs/build/doctrees/micro_dl.input.doctree
diff --git a/docs/build/doctrees/micro_dl.networks.doctree b/docs/build/doctrees/micro_dl.networks.doctree
diff --git a/docs/build/doctrees/micro_dl.networks.layers.doctree b/docs/build/doctrees/micro_dl.networks.layers.doctree
diff --git a/docs/build/doctrees/micro_dl.plotting.doctree b/docs/build/doctrees/micro_dl.plotting.doctree
diff --git a/docs/build/doctrees/micro_dl.preprocessing.doctree b/docs/build/doctrees/micro_dl.preprocessing.doctree
diff --git a/docs/build/doctrees/micro_dl.train.doctree b/docs/build/doctrees/micro_dl.train.doctree
diff --git a/docs/build/doctrees/micro_dl.utils.doctree b/docs/build/doctrees/micro_dl.utils.doctree
diff --git a/docs/build/doctrees/modules.doctree b/docs/build/doctrees/modules.doctree
diff --git a/docs/build/html/micro_dl.cli.html b/docs/build/html/micro_dl.cli.html
@@ -287,9 +287,17 @@ <h2>Submodules<a class="headerlink" href="#submodules" title="Permalink to this
 <dl class="py function">
 <dt class="sig sig-object py" id="micro_dl.cli.preprocess_script.parse_args">
 <span class="sig-prename descclassname"><span class="pre">micro_dl.cli.preprocess_script.</span></span><span class="sig-name descname"><span class="pre">parse_args</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#micro_dl.cli.preprocess_script.parse_args" title="Permalink to this definition"></a></dt>
-<dd><p>Parse command line arguments</p>
-<p>In python namespaces are implemented as dictionaries
-:return: namespace containing the arguments passed.</p>
+<dd><p>Parse command line arguments
+In python namespaces are implemented as dictionaries
+The preprocess_cli script takes as input a path to a configuration yaml file.
+For examples of preprocessing config files in 2.5D and 2D, see:
+<a class="reference external" href="https://github.com/mehta-lab/microDL/blob/main/config_files/Preprocessing-config_2.5DUnet_regression_phase2membrane.yml">https://github.com/mehta-lab/microDL/blob/main/config_files/Preprocessing-config_2.5DUnet_regression_phase2membrane.yml</a>
+<a class="reference external" href="https://github.com/mehta-lab/microDL/blob/main/config_files/Preprocessing-config_2DUnet_regression_phase2nucleus.yml">https://github.com/mehta-lab/microDL/blob/main/config_files/Preprocessing-config_2DUnet_regression_phase2nucleus.yml</a></p>
+<dl class="field-list simple">
+<dt class="field-odd">Returns</dt>
+<dd class="field-odd"><p>namespace containing the arguments passed.</p>
+</dd>
+</dl>
 </dd></dl>
 
 <dl class="py function">

diff --git a/docs/build/html/micro_dl.html b/docs/build/html/micro_dl.html
@@ -224,7 +224,7 @@ <h2>Submodules<a class="headerlink" href="#submodules" title="Permalink to this
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="micro_dl.networks.html">micro_dl.networks module</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="micro_dl.networks.html#subpackages">Subpackages</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="micro_dl.networks.html#submodules">Submodules</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="micro_dl.networks.layers.html">micro_dl.networks.layers module</a><ul>
 <li class="toctree-l4"><a class="reference internal" href="micro_dl.networks.layers.html#submodules">Submodules</a></li>
 <li class="toctree-l4"><a class="reference internal" href="micro_dl.networks.layers.html#module-micro_dl.networks.layers.interp_upsampling2D">micro_dl.networks.layers.interp_upsampling2D module</a></li>
@@ -234,7 +234,7 @@ <h2>Submodules<a class="headerlink" href="#submodules" title="Permalink to this
 </li>
 </ul>
 </li>
-<li class="toctree-l2"><a class="reference internal" href="micro_dl.networks.html#submodules">Submodules</a></li>
+<li class="toctree-l2"><a class="reference internal" href="micro_dl.networks.html#id1">Submodules</a></li>
 <li class="toctree-l2"><a class="reference internal" href="micro_dl.networks.html#module-micro_dl.networks.base_conv_net">micro_dl.networks.base_conv_net module</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="micro_dl.networks.html#micro_dl.networks.base_conv_net.BaseConvNet"><code class="docutils literal notranslate"><span class="pre">BaseConvNet</span></code></a><ul>
 <li class="toctree-l4"><a class="reference internal" href="micro_dl.networks.html#micro_dl.networks.base_conv_net.BaseConvNet.build_net"><code class="docutils literal notranslate"><span class="pre">BaseConvNet.build_net()</span></code></a></li>

diff --git a/docs/build/html/micro_dl.networks.html b/docs/build/html/micro_dl.networks.html
@@ -89,8 +89,8 @@
 
   <section id="micro-dl-networks-module">
 <h1>micro_dl.networks module<a class="headerlink" href="#micro-dl-networks-module" title="Permalink to this heading"></a></h1>
-<section id="subpackages">
-<h2>Subpackages<a class="headerlink" href="#subpackages" title="Permalink to this heading"></a></h2>
+<section id="submodules">
+<h2>Submodules<a class="headerlink" href="#submodules" title="Permalink to this heading"></a></h2>
 <div class="toctree-wrapper compound">
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="micro_dl.networks.layers.html">micro_dl.networks.layers module</a><ul>
@@ -121,8 +121,8 @@ <h2>Subpackages<a class="headerlink" href="#subpackages" title="Permalink to thi
 </ul>
 </div>
 </section>
-<section id="submodules">
-<h2>Submodules<a class="headerlink" href="#submodules" title="Permalink to this heading"></a></h2>
+<section id="id1">
+<h2>Submodules<a class="headerlink" href="#id1" title="Permalink to this heading"></a></h2>
 </section>
 <section id="module-micro_dl.networks.base_conv_net">
 <span id="micro-dl-networks-base-conv-net-module"></span><h2>micro_dl.networks.base_conv_net module<a class="headerlink" href="#module-micro_dl.networks.base_conv_net" title="Permalink to this heading"></a></h2>
@@ -436,7 +436,7 @@ <h2>Submodules<a class="headerlink" href="#submodules" title="Permalink to this
 <dd><p>This is where the layer’s logic lives.</p>
 <dl class="simple">
 <dt># Arguments</dt><dd><p>inputs: Input tensor, or list/tuple of input tensors.
-<a href="#id1"><span class="problematic" id="id2">**</span></a>kwargs: Additional keyword arguments.</p>
+<a href="#id2"><span class="problematic" id="id3">**</span></a>kwargs: Additional keyword arguments.</p>
 </dd>
 <dt># Returns</dt><dd><p>A tensor or list/tuple of tensors.</p>
 </dd>

diff --git a/docs/build/html/modules.html b/docs/build/html/modules.html
@@ -106,8 +106,8 @@ <h1>micro_dl<a class="headerlink" href="#micro-dl" title="Permalink to this head
 </ul>
 </li>
 <li class="toctree-l3"><a class="reference internal" href="micro_dl.networks.html">micro_dl.networks module</a><ul>
-<li class="toctree-l4"><a class="reference internal" href="micro_dl.networks.html#subpackages">Subpackages</a></li>
 <li class="toctree-l4"><a class="reference internal" href="micro_dl.networks.html#submodules">Submodules</a></li>
+<li class="toctree-l4"><a class="reference internal" href="micro_dl.networks.html#id1">Submodules</a></li>
 <li class="toctree-l4"><a class="reference internal" href="micro_dl.networks.html#module-micro_dl.networks.base_conv_net">micro_dl.networks.base_conv_net module</a></li>
 <li class="toctree-l4"><a class="reference internal" href="micro_dl.networks.html#module-micro_dl.networks.base_image_to_vector_net">micro_dl.networks.base_image_to_vector_net module</a></li>
 <li class="toctree-l4"><a class="reference internal" href="micro_dl.networks.html#module-micro_dl.networks.base_unet">micro_dl.networks.base_unet module</a></li>

diff --git a/docs/build/html/searchindex.js b/docs/build/html/searchindex.js
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1 @@
+<meta http-equiv="refresh" content="0; url=./build/html/index.html" />
diff --git a/docs/readme.md b/docs/readme.md
@@ -1,7 +1,3 @@
----
-permalink: ./build/html/index.html
----
-
 # Auto-Documentation
 
 # Sphinx
@@ -30,3 +26,11 @@ Check for error messages and warning to make sure all docstring are correctly fo
 
 Once updated docs are merged into main, the documentation can be hosted e.g. on
 [GitHub Pages.](https://pages.github.com/)
+
+There's a GitHub actions workflow (actions_docs.yml) that will 
+automatically build the docs and push to the gh-pages branch when there's a push to the main branch.
+The documentation will then be pushed to GitHub pages and the documentation is
+published [here.](https://mehta-lab.github.io/microDL/)
+
+Note: Python version is currently old because microDL version 1.0.0 still supports tensorflow.
+Please update when updating to version 2.0.0.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -18,7 +18,7 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.autodoc', 'sphinx_rtd_theme']
 
 templates_path = ['_templates']
 exclude_patterns = []

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,6 +6,24 @@
 Welcome to microDL's documentation!
 ===================================
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Introduction:
+
+microDL is a deep learning framework for processing microscopy data.
+The framework consists of:
+
+* Preprocessing: Flatfield correction, mask creation and normalization.
+* Training: Building and training 2.5D or 2D U-Net models for regression or segmentation.
+* Inference: Use your trained model to predict full size images.
+
+These pages offers in depth descriptions of the functions and classes of microDL and is mainly
+intended for developers,
+and users who would like to understand the details.
+If you're a user and are mainly interested in understanding how to run microDL,
+please see the `GitHub repository <https://github.com/mehta-lab/microDL>`_ and the readme markdown files within it.
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents: