rm lingering docs/source, add environment.yml, a few extra testing deps, other docs updates

docs/building/building_tools.md

@@ -70,6 +70,8 @@ Once you've built a tool, it needs to be calibrated for use on the machine. See
 [Tool Postreqs](tool_postreqs)
 
 ```{toctree}
+:hidden:
+
 tool_prereqs
 pipette_tool
 inoculation_tool

docs/building/index.md

@@ -7,17 +7,44 @@ title: Build Guides
 
 To use `science-jubilee`, you'll need to build both the Jubilee motion platform as well as tools to use on the machine.
 
-## Building a Jubilee
+```{eval-rst}
+.. grid:: 1 2 2 2
+    :gutter: 4
+    :padding: 2 2 0 0
+    :class-container: sd-text-center
 
-To use a Jubilee for laboratory automation, you first need a Jubilee! This guide collates resources to build the Jubilee motion platform.
+    .. grid-item-card:: Building a Jubilee
+        :class-card: intro-card
+        :shadow: md
 
-[Jubilee Build Resources](building_a_jubilee)
+        To use a Jubilee for laboratory automation, you first need a Jubilee! This guide collates resources to build the Jubilee motion platform.
 
-## Building Science Jubilee Tools
+        +++
 
-Once you have a motion platform, you can add tools relevant to your application. Existing tools for laboratory automation are documented on this page.
+        .. button-ref:: jubilee-build-resources
+            :ref-type: ref
+            :click-parent:
+            :color: secondary
+            :expand:
 
-[Laboratory Automation Tools](building_tools)
+            Jubilee Build Resources
+
+    .. grid-item-card:: Building Science Jubilee Tools
+        :class-card: intro-card
+        :shadow: md
+
+        Once you have a motion platform, you can add tools relevant to your application. Existing tools for laboratory automation are documented on this page.
+
+        +++
+
+        .. button-ref:: building-science-jubilee-tools
+            :ref-type: ref
+            :click-parent:
+            :color: secondary
+            :expand:
+
+            Laboratory Automation Tools
+```
 
 ```{toctree}
 :hidden:

docs/building/inoculation_tool.md

@@ -5,7 +5,11 @@ title: Inoculation Loop Tool
 (inoculation-loop-tool)=
 # Inoculation Loop Tool
 
-![Inoculation loop dipping into a well to pick up duckweed fronds](_static/loop-dip.png){scale="25%" alt="Inoculation loop dipping into well."}
+```{figure} _static/loop-dip.png
+:scale: 25 %
+
+Inoculation loop dipping into a well to pick up duckweed fronds.
+```
 
 The inoculation loop tool uses the existing [pen tool](https://jubilee3d.com/index.php?title=Passive_Pen_Tool) to hold an inoculation loop or other probes.
 

docs/building/pipette_tool.md

@@ -5,9 +5,17 @@ title: Pipette Tool
 (pipette-tool)=
 # Pipette Tool
 
-![Front & back of the pipette tool](_static/pipette-flexure.jpg){scale="50%" alt="Front and back of the pipette tool."}
+```{figure} _static/pipette-flexure.jpg
+:scale: 50 %
 
-![Picking up a pipette tip](_static/pickup.gif){scale="40%" alt="Pipette tool picking up a tip"}
+Front and back of the pipette tool.
+```
+
+```{figure} _static/pickup.gif
+:scale: 40 %
+
+Pipette tool picking up a tip.
+```
 
 ## Parts to Buy
 

docs/building/side_camera_tool.md

@@ -5,7 +5,11 @@ title: Side Camera Tool
 (side-camera-tool)=
 # Side Camera Tool
 
-![Side Camera tool parked on a Jubilee](_static/side-camera.png){scale="25%"}
+```{figure} _static/side-camera.png
+:scale: 50 %
+
+Side Camera tool parked on a Jubilee.
+```
 
 ## Parts to Buy
 

docs/building/tool_prereqs.md

@@ -11,9 +11,11 @@ title: Tool Prerequisites
 
 Jubilee tools are parked on the rear rail of the machine. To hold the tool when it's not in use, any tool will need a parking post. Several sizes already exist to accommodate tools of varying widths. More info [here](https://jubilee3d.com/index.php?title=Parking_Post).
 
+```{figure}
 ![A Jubilee parking post](_static/parking-post.png){scale="50%"}
 
 Diagram of a Jubilee parking post.
+```
 
 ### Tool Wings
 
@@ -23,9 +25,11 @@ Each tool needs a way to rest on top of the pins of the parking post above. Whil
 
 Each tool has a tool plate which couples with Jubilee's toolchanger to be able to be picked up. This tool plate can be 3D printed + laser cut, or you can purchase aluminum toolplates.
 
-![Tools parked on a Jubilee](_static/tools.png){scale="10%"}
+```{figure} _static/tools.png
+:scale: 15 %
 
 Shown are a set of tools parked on a Jubilee; seen on the side of each tool frame are a set of tool wings resting on an accompanying parking post. The tool plates of each tool are visible; note the three threaded steel balls on each which will couple with toolchanger on pickup, and the white wedge plate (made of delrin) in the center.
+```
 
 ## Fabricating a Tool
 

docs/building/top_down_camera_tool.md

@@ -5,7 +5,11 @@ title: Camera Tool
 (camera-tool)=
 # Camera Tool
 
-![Timelapse of duckweed growing](_static/duckweed.gif){scale="25%"}
+```{figure} _static/duckweed.gif
+:scale: 25 %
+
+Timelapse of duckweed growing.
+```
 
 A timelapse of duckweed frond growth, taken with the Jubilee camera tool.
 

docs/development/contributing_docs.md

@@ -7,32 +7,31 @@ title: Documentation Contribution Guidelines
 
 ## Documentation Overview
 
-Most development starts with a GitHub Issue. See more about issues on the [Development page](https://machineagency.github.io/science-jubilee/development/index.html). The documentation consists of the documentation pages (like this one) and inline code documentation to generate the code reference. The documentation pages can be found in `science_jubilee/docs/source`. We use [Sphinx](https://www.sphinx-doc.org/en/master/) to generate the documentation, which in turn uses the ReStructured Text markup language. The inline code can be found immediately after all functions in the `science-jubilee` package.
+Most development starts with a GitHub Issue. See more about issues on the [Development page](https://machineagency.github.io/science-jubilee/development/index.html). The documentation consists of the documentation pages (like this one) and inline code documentation to generate the code reference. The documentation pages can be found in `science_jubilee/docs/source`. We use [Sphinx](https://www.sphinx-doc.org/en/master/) to generate the documentation, which in turn uses the [Markedly Structured Text (MyST) Parser](https://myst-parser.readthedocs.io/). MyST provides flexibility in that you can use standard Markdown files while exposing the more advanced features of the ReStructuredText (RST) format. The inline code can be found immediately after all functions in the `science-jubilee` package.
 
-This page provides information on how the documentation is organized and how it can be modified. To make and submit changes to the documentation, please follow the same steps outlined in the Code Contribution Guidelines.
+See below for information on how the documentation is organized and how it can be modified. For simple edits (e.g., fixing typos or adding clarification), simply click the "Edit on Github" button at the upper-right of the corresponding page. To make and submit more involved changes to the documentation, please follow the same steps outlined in the [Code Contribution Guidelines](#code-contribution-guidelines).
 
 ### Building the Docs
 
-All of the packages necessary to build the documentation are specified in `setup.py`, so you should be immediately able to build the documentation. To do so, ensure the virtual environment is activated. Then:
+If you install the `science-jubilee` conda environment, all of the packages necessary to build the documentation should be installed automatically (make sure to `conda activate science-jubilee`). Otherwise, you will need to run `pip install -r docs/requirements.txt` in your environment first. Then, run the following lines:
 
 ```bash
 cd docs
 make html
 ```
 
-You can preview the changes in the `build/html` folder; the build folder is added to `.gitignore` by default which means this won't be added to the repository.
+You can preview the changes in the `_build/html` folder, which is untracked by git, as specified in `.gitignore`. Within VS Code for example, you can install the [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) extension, right-click on `docs/_build/html/index.html`, and select "Open with Live Server" to dynamically view the documentation. Run `make html` within the `docs` folder each time you'd like to view the changes.
 
 ### Adding New Pages
 
-If you are adding new documentation pages, make sure to add a label at the top of your new `.md` file like so:
+If you are adding new documentation pages, make sure to add a target header at the top of your new `.md` file, just before the top-level heading:
 
-```rst
-.. _
-
-<label>:
+```markdown
+(my-target-header)=
+# My Top-level Heading
 ```
 
-where you should replace `<label>` (including the angle brackets) with your label name. Sphinx has a nice primer on using reStructured Text [here](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html).
+Click the "Show Source" button on the upper-right of this page to see a real example in this project. Refer to https://myst-parser.readthedocs.io/ for more information.
 
 ### Adding Inline Documentation
 

environment.yml

@@ -0,0 +1,22 @@
+name: science-jubilee
+channels:
+  - defaults
+  - conda-forge
+dependencies:
+  - python>=3.6
+  - pip
+  # BASICS
+  - ipython
+  - ipykernel
+  - pip:
+     - -e .  # install git checkout of ac-microcourses in editable mode
+     - -r docs/requirements.txt  # install docs requirements
+     # add here only pip-packages that are not available in conda/conda-forge! E.g.:
+    #  - some-package
+
+  # DEVELOPMENT ONLY PACKAGES (could also be kept in a separate environment file)
+  - pytest
+  - pytest-cov
+  - tox
+  - pre_commit
+  - sphinx

setup.cfg

@@ -69,6 +69,10 @@ testing =
     setuptools
     pytest
     pytest-cov
+    pre-commit
+    sphinx
+    tox
+
 
 [options.entry_points]
 # Add here console scripts like: