diff --git a/docs/building/building_tools.md b/docs/building/building_tools.md index 77100d0..9723a1e 100644 --- a/docs/building/building_tools.md +++ b/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 diff --git a/docs/building/index.md b/docs/building/index.md index 28f522e..0bc07f4 100644 --- a/docs/building/index.md +++ b/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: diff --git a/docs/building/inoculation_tool.md b/docs/building/inoculation_tool.md index e40ebaf..e1a658d 100644 --- a/docs/building/inoculation_tool.md +++ b/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. diff --git a/docs/building/pipette_tool.md b/docs/building/pipette_tool.md index 82b937f..f637b7a 100644 --- a/docs/building/pipette_tool.md +++ b/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 diff --git a/docs/building/side_camera_tool.md b/docs/building/side_camera_tool.md index e1df31e..c2ec1cd 100644 --- a/docs/building/side_camera_tool.md +++ b/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 diff --git a/docs/building/tool_prereqs.md b/docs/building/tool_prereqs.md index ab9612a..21073c7 100644 --- a/docs/building/tool_prereqs.md +++ b/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 diff --git a/docs/building/top_down_camera_tool.md b/docs/building/top_down_camera_tool.md index 5150bc6..133d826 100644 --- a/docs/building/top_down_camera_tool.md +++ b/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. diff --git a/docs/development/contributing_docs.md b/docs/development/contributing_docs.md index 4fcb2e7..b0960fe 100644 --- a/docs/development/contributing_docs.md +++ b/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 -.. _ - -