Merge pull request #1052 from TheDeanLab/docs-update

AdvancedImagingUTSW · web-flow · commit 19bb66b03a87 · 2024-12-30T09:32:32.000-06:00
Link check with Sphinx
diff --git a/.github/workflows/build_docs.yaml b/.github/workflows/build_docs.yaml
@@ -52,7 +52,6 @@ jobs:
         run: pwd
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
-        # if: ${{ github.ref == 'refs/heads/main' }}
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs/build/html
diff --git a/docs/make.bat b/docs/make.bat
@@ -1,38 +1,50 @@
 @ECHO OFF
 
+REM Save the current directory and change to the script's directory
 pushd %~dp0
 
 REM Command file for Sphinx documentation
 
+REM Set the SPHINXBUILD variable if it is not already set
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
+
+REM Define the source and build directories
 set SOURCEDIR=source
 set BUILDDIR=build
 
+REM Check if sphinx-build is available
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have
-Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to
-point
-	echo.to the full path of the 'sphinx-build' executable.
-Alternatively you
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
 	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
 	echo.https://www.sphinx-doc.org/
 	exit /b 1
 )
 
+REM If no argument is provided, show help
 if "%1" == "" goto help
 
+REM Handle the linkcheck target
+if "%1" == "linkcheck" (
+    %SPHINXBUILD% -b linkcheck %SOURCEDIR% %BUILDDIR%/linkcheck %SPHINXOPTS% %O%
+    goto end
+)
+
+REM Run the specified target
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
 :end
+
+REM Return to the original directory
 popd
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -109,6 +109,11 @@
 
 pygments_style = "sphinx"
 
+# -- Linkcheck Options ---------------------------------------------
+linkcheck_ignore = [
+    r'http://proxy\.your_university\.edu:1234',
+    r'https://proxy\.your_university\.edu:1234'
+]
 # -- LaTeX output options ----------------------------------------------------
 
 latex_elements = {
diff --git a/docs/source/intermediate.rst b/docs/source/intermediate.rst
@@ -4,9 +4,9 @@ Write A Smart Acquisition Routine (Intermediate)
 
 **navigate**'s :doc:`feature container <contributing/feature_container>` enables us to
 write acquisition routines on the fly by chaining existing 
-:doc:`features <user_guide/features>` into lists. Please see
+:doc:`features <user_guide/features/features>` into lists. Please see
 :ref:`Currently Implemented Features <contributing/feature_container:currently implemented features>`
-for a complete list of features. Users can build additionals feature within :doc:`plugins <plugin/plugin_home>`.
+for a complete list of features. Users can build additional features within :doc:`plugins <plugin/plugin_home>`.
 
 In this guide, we will use existing features to write a routine that scans through an 
 imaging chamber and takes z-stacks only where it finds the sample.
diff --git a/docs/source/software_installation.rst b/docs/source/software_installation.rst
@@ -193,7 +193,7 @@ Developer install
 
 If you do not have `Git already installed <https://git-scm.com/downloads>`_, you will
 need to do so before downloading the repo. We also recommend installing
-`GitHub Desktop <https://desktop.github.com/>`_ for a more user-friendly experience.
+`GitHub Desktop <https://github.com/apps/desktop>`_ for a more user-friendly experience.
 
 **Create a directory where the repository will be cloned**
     We recommend a path/location that is easy to find and access such as the your
diff --git a/docs/source/user_guide/acquiring_guide.rst b/docs/source/user_guide/acquiring_guide.rst
@@ -18,8 +18,7 @@ Saving is toggled under the GUI's :ref:`timepoint settings <user_guide/gui_walkt
 These modes (and other custom modes) can be selected in the program's
 :ref:`acquisition bar <user_guide/gui_walkthrough:acquisition bar>` dropdown list.
 
-Each acquisition mode is implemented as a :doc:`feature list <features>` and can be used
-in sequence with other features that can, for example,
+Each acquisition mode is implemented as a :doc:`feature list <features/features>` and can be used in sequence with other features that can, for example,
 :doc:`make smart decisions <../intermediate>`.
 
 ----------------
@@ -32,8 +31,8 @@ this mode, only to preview what is in focus. This mode is helpful for alignment,
 parameter tuning, and scrolling around the sample with the stage.
 
 It is implemented as
-a :doc:`feature list <features>`, shown in its
-:ref:`textual form <user_guide/features:text representation of feature lists>` below.
+a :doc:`feature list <features/features>`, shown in its
+:ref:`textual form <user_guide/features/features:text representation of feature lists>` below.
 
 .. code-block:: python
 
@@ -105,7 +104,7 @@ Customized
 
 The customized acquisition mode can be used to run any feature list of the user's choosing.
 Data acquisition with **navigate** is almost infinitely reconfigurable with the either the
-:doc:`feature container <features>`, if a desired acquisition can be
+:doc:`feature container <features/features>`, if a desired acquisition can be
 performed using a reconfiguration of existing features and saving formats, or the
 :doc:`plugin architecture <../plugin/plugin_home>`, if new features or saving formats are
 required. We strongly recommend the reader check through the
diff --git a/docs/source/user_guide/features/features.rst b/docs/source/user_guide/features/features.rst
@@ -213,9 +213,9 @@ As an example, let's look at the feature list that describes the
 Here, we have a sequence defined by ``[]`` containing one element, a loop, indicated
 by the closed parentheses. There are two features within this loop. One feature has the
 name
-:doc:`PrepareNextChannel <../_autosummary/navigate.model.features.common_features.PrepareNextChannel>`
+:doc:`PrepareNextChannel <../../_autosummary/navigate.model.features.common_features.PrepareNextChannel>`
 and the other
-:doc:`LoopByCount <../_autosummary/navigate.model.features.common_features.LoopByCount>`.
+:doc:`LoopByCount <../../_autosummary/navigate.model.features.common_features.LoopByCount>`.
 The parentheses indicate we will keep looping through both of these features until
 stopping criteria is met. In this case, the looping will stop when ``LoopByCount``
 returns ``False`` due to running out of ``selected_channels`` to loop through. That is,
diff --git a/docs/source/user_guide/gui_walkthrough.rst b/docs/source/user_guide/gui_walkthrough.rst
@@ -101,7 +101,7 @@ Features
 
 This menu provides access to acquisition feature lists. An explanation of features,
 feature lists, and the use and operation of this menu is provided under
-:doc:`Reconfigurable Acquisitions Using Features <features>`.
+:doc:`Reconfigurable Acquisitions Using Features <features/features>`.
 
 -------------------
 
@@ -719,7 +719,7 @@ Autofocus Settings
 .. image:: case_studies/images/autofocus_settings.png
 
 The :guilabel:`Autofocus Settings` panel controls parameters of the autofocus
-:doc:`feature <features>`.
+:doc:`feature <features/features>`.
 
 * :guilabel:`Device Type` indicates if the autofocus routine should be applied to a
   stage or to a remote focus device.
diff --git a/docs/source/user_guide/hardware/stage.rst b/docs/source/user_guide/hardware/stage.rst
@@ -275,7 +275,7 @@ Physik Instrumente
 ------------------
 
 These stages are controlled by `PI <https://www.pi-usa.us/en/>`_'s own
-`Python code <https://pypi.org/project/PIPython/>`_ and are quite stable.
+`Python code <https://pypi.org/project/PIPython/>`_.
 
 .. note::
 
@@ -285,19 +285,22 @@ These stages are controlled by `PI <https://www.pi-usa.us/en/>`_'s own
     - PIMikroMove: 2.36.1.0
     - PI_GCS2_DLL: 3.22.0.0
 
-
-They
-include a special ``hardware`` option, ``refmode``, which corresponds to how the
-PI stage chooses to self-reference. Options are ``REF``, ``FRF``, ``MNL``, ``FNL``,
-``MPL`` or ``FPL``. These are PI's GCS commands, and the correct reference mode
-for your stage should be found by launching PIMikroMove, which should come with
-your stage. Stage names (e.g. ``L-509.20DG10``) can also be found in PIMikroMove
-or on a label on the side of your stage.
-
 .. note::
-    PI L-509.20DG10 has a unidirectional repeatability of 100 nm, bidirectional
-    repeatability of 2 microns, and a minimum incremental motion of 100 nm.
-    This is potentially too coarse.
+    PI stages require a special ``hardware`` option in the configuration.yaml file, ``refmode``,
+    which corresponds to how the PI stage chooses to self-reference. Options are:
+
+    * ``REF``
+    * ``FRF``
+    * ``MNL``
+    * ``FNL``
+    * ``MPL``
+    * ``FPL``
+    * ``" "`` - An empty string can be provided if no stage referencing mode is needed.
+
+    These are PI's GCS commands, and the correct reference mode for your stage should be found by
+    launching PIMikroMove, which comes with your stage and can be downloaded
+    `here <https://www.pi-usa.us/en/products/controllers-drivers-motion-control-software/motion-control-software>`_.
+    Stage names (e.g. ``L-509.20DG10``) can also be found in PIMikroMove or on a label on the side of your stage.
 
 -----------------
 
diff --git a/docs/source/user_guide/software_configuration.rst b/docs/source/user_guide/software_configuration.rst
@@ -95,7 +95,7 @@ along in this file when reading the next sections.
 
 See the :ref:`Setting up an Axially Swept Light-Sheet Microscope <setup_aslm>` case
 study for a general walkthrough of how to build your own configuration file and see
-:doc:`Implementations <implemented_microscopes>` for examples of configuration files.
+:doc:`Implementations <../implementations/implementations>` for examples of configuration files.
 
 -----------------
 
@@ -165,7 +165,7 @@ Each microscope is expected to have a ``daq``, ``camera``, ``remote_focus_device
 can be specified as synthetic.
 
 Most of the information to set up these devices can be found in the
-:doc:`Supported Hardware <hardware_overview>` section of the documentation.
+:doc:`Supported Hardware <hardware/hardware_home>` section of the documentation.
 Additional explanations of a few specific sections of the microscope configuration are
 below. Notably, the ``zoom`` section of the ``configuration.yaml`` specifies effective
 pixel size.
