Documentation Update (#678)

* Updated TheiaEuk_Illumina diagram * Delete docs/assets/figures/TheiaEuk_Illumina_PHB 20241106.png Space in the name was causing an issue * New TheiaEuk_Illumina diagram no space in name * Update theiaeuk.md wf diagram * Combine documentation efforts (#671) * update remaining broken links * improvements * update org-specifc theiaeuk * make pretty * rename * add link to template * remove construction banner * update contrib guide * remove \| bars --------- Co-authored-by: Sage Wright <[email protected]>
theiagen · Dec 3, 2024 · 12404d8 · 12404d8
1 parent b4aad55
commit 12404d8
Show file tree

Hide file tree

Showing 15 changed files with 388 additions and 208 deletions.
diff --git a/docs/assets/figures/TheiaEuk_Illumina_PHB_20241106.png b/docs/assets/figures/TheiaEuk_Illumina_PHB_20241106.png
diff --git a/docs/assets/new_workflow_template.md b/docs/assets/new_workflow_template.md
@@ -4,14 +4,16 @@
 
 | **Workflow Type** | **Applicable Kingdom** | **Last Known Changes** | **Command-line Compatibility** | **Workflow Level** |
 |---|---|---|---|---|
-| [Workflow Type](../../workflows_overview/workflows_type.md/#link-to-workflow-type) | [Applicable Kingdom](../../workflows_overview/workflows_kingdom.md/#link-to-applicable-kingdom) | PHB <version with last changes> | <command-line compatibility> | <workflow level on terra> |
+| [Link to Workflow Type](../../workflows_overview/workflows_type.md/#link-to-workflow-type) | [Link to Applicable Kingdom](../../workflows_overview/workflows_kingdom.md/#link-to-applicable-kingdom) | PHB <version with last changes\> | <command-line compatibility\> | <workflow level on terra (set or sample)\> |
 
 ## Workflow_Name_On_Terra
 
 Description of the workflow.
 
 ### Inputs
 
+Input should be ordered as they appear on Terra
+
 | **Terra Task Name** | **Variable** | **Type** | **Description** | **Default Value** | **Terra Status** |
 |---|---|---|---|---|---|
 | task_name | **variable_name** | Type | Description | Default Value | Required/Optional |
@@ -24,12 +26,12 @@ Description of the workflow tasks
     Description of the task
 
     !!! techdetails "Tool Name Technical Details"
-        |  | Links | 
-        | --- | --- | 
+        |  | Links |
+        | --- | --- |
         | Task | [link to task on GitHub] |
         | Software Source Code | [link to tool's source code] |
         | Software Documentation | [link to tool's documentation] |
-        | Original Publication | [link to tool's publication] |
+        | Original Publication(s) | [link to tool's publication] |
 
 ### Outputs
 

diff --git a/docs/contributing/doc_contribution.md b/docs/contributing/doc_contribution.md
@@ -14,7 +14,7 @@ To test your documentation changes, you will need to have the following packages
 pip install mkdocs-material mkdocs-material-extensions mkdocs-git-revision-date-localized-plugin mike mkdocs-glightbox
 ```
 
-The live preview server can be activated by running the following command:
+Once installed, navigate to the top directory in PHB. The live preview server can be activated by running the following command:
 
 ```bash
 mkdocs serve
@@ -34,49 +34,7 @@ Here are some VSCode Extensions can help you write and edit your markdown files
 
 - [Excel to Markdown Table](https://tableconvert.com/excel-to-markdown) - This website will convert an Excel table into markdown format, which can be copied and pasted into your markdown file.
 - [Material for MkDocs Reference](https://squidfunk.github.io/mkdocs-material/reference/) - This is the official reference for the Material for MkDocs theme, which will help you understand how to use the theme's features.
-- [Broken Link Check](https://www.brokenlinkcheck.com/) - This website will scan your website to ensure that all links are working correctly. This will only work on the deployed version of the documentation, not the local version.
-
-## Documentation Structure
-
-A brief description of the documentation structure is as follows:
-
-- `docs/` - Contains the Markdown files for the documentation.
-    - `assets/` - Contains images and other files used in the documentation.
-        - `figures/` - Contains images, figures, and workflow diagrams used in the documentation. For workflows that contain many images (such as BaseSpace_Fetch), it is recommended to create a subdirectory for the workflow.
-        - `files/` - Contains files that are used in the documentation. This may include example outputs or templates. For workflows that contain many files (such as TheiaValidate), it is recommended to create a subdirectory for the workflow.
-        - `logos/` - Contains Theiagen logos and symbols used int he documentation.
-        - `metadata_formatters/` - Contains the most up-to-date metadata formatters for our submission workflows.
-        - `new_workflow_template.md` - A template for adding a new workflow page to the documentation.
-    - `contributing/` - Contains the Markdown files for our contribution guides, such as this file
-    - `javascripts/` - Contains JavaScript files used in the documentation.
-        - `tablesort.js` - A JavaScript file used to enable table sorting in the documentation.
-    - `overrides/` - Contains HTMLs used to override theme defaults
-        - `main.html` - Contains the HTML used to display a warning when the latest version is not selected
-    - `stylesheets/` - Contains CSS files used in the documentation.
-        - `extra.css` - A custom CSS file used to style the documentation; contains all custom theme elements (scrollable tables, resizable columns, Theiagen colors), and custom admonitions.
-    - `workflows/` - Contains the Markdown files for each workflow, organized into subdirectories by workflow category
-    - `workflows_overview/` - Contains the Markdown files for the overview tables for each display type: alphabetically, by applicable kingdom, and by workflow type.
-    - `index.md` - The home/landing page for our documentation.
-
-### Adding a Page for a New Workflow {#new-page}
-
-If you are adding a new workflow, there are a number of things to do in order to include the page in the documentation:
-
-1. Add a page with the title of the workflow to appropriate subdirectory in `docs/workflows/`. Feel free to use the template found in the `assets/` folder.
-2. Collect the following information for your new workflow:
-     - Workflow Name - Link the name with a relative path to the workflow page in appropriate `docs/workflows/` subdirectory
-     - Workflow Description - Brief description of the workflow
-     - Applicable Kingdom - Options: "Any taxa", "Bacteria", "Mycotics", "Viral"
-     - Workflow Level (_on Terra_) - Options: "Sample-level", "Set-level", or neither
-     - Command-line compatibility - Options: "Yes", "No", and/or "Some optional features incompatible"
-     - The version where the last known changes occurred (likely the upcoming version if it is a new workflow)
-     - Link to the workflow on Dockstore (if applicable) - Workflow name linked to the information tab on Dockstore.
-3. Format this information in a table.
-4. Copy the previously gathered information to ==**ALL THREE**== overview tables in `docs/workflows_overview/`:
-     - `workflows_alphabetically.md` - Add the workflow in the appropriate spot based on the workflow name.
-     - `workflows_kingdom.md` - Add the workflow in the appropriate spot(s) based on the kingdom(s) the workflow is applicable to. Make sure it is added alphabetically within the appropriate subsection(s).
-     - `workflows_type.md` - Add the workflow in the appropriate spot based on the workflow type. Make sure it is added alphabetically within the appropriate subsection.
-5. Copy the path to the workflow to ==**ALL**== of the appropriate locations in the `mkdocs.yml` file (under the `nav:` section) in the main directory of this repository. These should be the exact same spots as in the overview tables but without additional information. This ensures the workflow can be accessed from the navigation sidebar.
+- [Dead Link Check](https://www.deadlinkchecker.com/) - This website will scan your website to ensure that all links are working correctly. This will only work on the deployed version of the documentation, not the local version.
 
 ## Standard Language & Formatting Conventions
 
@@ -98,10 +56,11 @@ The following language conventions should be followed when writing documentation
 - **Bold Text** - Use `**bold text**` to indicate text that should be bolded.
 - _Italicized Text_ - Use `_italicized text_` to indicate text that should be italicized.
 - ==Highlighted Text== - Use `==highlighted text==` to indicate text that should be highlighted.
-- `Code` - Use \`code\` to indicate text that should be formatted as code.
+- `Code` - Use ````code` ``` (backticks) to indicate text that should be formatted as code.
 - ^^Underlined Text^^ - Use `^^underlined text^^` to indicate text that should be underlined (works with our theme; not all Markdown renderers support this).
 - > Citations
     - Use a `>` to activate quote formatting for a citation. Make sure to separate multiple citations with a comment line (`<!-- -->`) to prevent the citations from running together.
+    - Use a reputable citation style (e.g., Vancouver, Nature, etc.) for all citations.
 - Callouts/Admonitions - These features are called "call-outs" in Notion, but are "Admonitions" in MkDocs. [I highly recommend referring to the Material for MkDocs documentation page on Admonitions to learn how best to use this feature](https://squidfunk.github.io/mkdocs-material/reference/admonitions/). Use the following syntax to create a callout:
 
     ```markdown
@@ -116,26 +75,45 @@ The following language conventions should be followed when writing documentation
     !!! dna
         This is a DNA admonition. Admire the cute green DNA emoji. You can create this with the `!!! dna` syntax.
 
+        Use this admonition when wanting to convey general information or highlight specific facts.
+
     ???+ toggle
         This is a toggle-able section. The emoji is an arrow pointing to the right downward. You can create this with the `??? toggle` syntax. I have added a `+` at the end of the question marks to make it open by default.
 
+        Use this admonition when wanting to provide additional _optional_ information or details that are not strictly necessary, or take up a lot of space.
+
     ???+ task
         This is a toggle-able section **for a workflow task**. The emoji is a gear. Use the `??? task` syntax to create this admonition. Use `!!! task` if you want to have it be permanently expanded. I have add a `+` at the end of the question marks to make this admonition open by default and still enable its collapse.
 
+        Use this admonition when providing details on a workflow, task, or tool.
+
     !!! caption
-        This is a caption. The emoji is a painting. You can create this with the `!!! caption` syntax. This is used to enclose an image in a box and looks nice. A caption can be added beneath the picture and will also look nice.
+        This is a caption. The emoji is a painting. You can create this with the `!!! caption` syntax. A caption can be added beneath the picture and will also look nice.
+
+        Use this admonition when including images or diagrams in the documentation.
 
     !!! techdetails
         This is where you will put technical details for a workflow task. You can create this by `!!! techdetails` syntax.
 
+        Use this admonition when providing technical details for a workflow task or tool. These admonitions should include the following table:
+
+        |  | Links |
+        | --- | --- |
+        | Task | [link to the task file in the PHB repository on GitHub] |
+        | Software Source Code | [link to tool's source code] |
+        | Software Documentation | [link to tool's documentation] |
+        | Original Publication(s) | [link to tool's publication] |
+
+        If any of these items are unfillable, delete the row.
+
 - Images - Use the following syntax to insert an image:
 
     ```markdown
     !!! caption "Image Title"
         ![Alt Text](/path/to/image.png)
     ```
 
-- Indentation - **_FOUR_** spaces are required instead of the typical two. This is a side effect of using this theme. If you use two spaces, the list and/or indentations will not render correctly. This will make your linter sad :( 
+- Indentation - **_FOUR_** spaces are required instead of the typical two. This is a side effect of using this theme. If you use two spaces, the list and/or indentations will not render correctly. This will make your linter sad :(
 
     ```markdown
     - first item
@@ -160,3 +138,45 @@ The following language conventions should be followed when writing documentation
     ```
 
 - End all pages with an empty line
+
+## Documentation Structure
+
+A brief description of the documentation structure is as follows:
+
+- `docs/` - Contains the Markdown files for the documentation.
+    - `assets/` - Contains images and other files used in the documentation.
+        - `figures/` - Contains images, figures, and workflow diagrams used in the documentation. For workflows that contain many images (such as BaseSpace_Fetch), it is recommended to create a subdirectory for the workflow.
+        - `files/` - Contains files that are used in the documentation. This may include example outputs or templates. For workflows that contain many files (such as TheiaValidate), it is recommended to create a subdirectory for the workflow.
+        - `logos/` - Contains Theiagen logos and symbols used int he documentation.
+        - `metadata_formatters/` - Contains the most up-to-date metadata formatters for our submission workflows.
+        - `new_workflow_template.md` - A template for adding a new workflow page to the documentation. You can see this template [here](../assets/new_workflow_template.md)
+    - `contributing/` - Contains the Markdown files for our contribution guides, such as this file
+    - `javascripts/` - Contains JavaScript files used in the documentation.
+        - `tablesort.js` - A JavaScript file used to enable table sorting in the documentation.
+    - `overrides/` - Contains HTMLs used to override theme defaults
+        - `main.html` - Contains the HTML used to display a warning when the latest version is not selected
+    - `stylesheets/` - Contains CSS files used in the documentation.
+        - `extra.css` - A custom CSS file used to style the documentation; contains all custom theme elements (scrollable tables, resizable columns, Theiagen colors), and custom admonitions.
+    - `workflows/` - Contains the Markdown files for each workflow, organized into subdirectories by workflow category
+    - `workflows_overview/` - Contains the Markdown files for the overview tables for each display type: alphabetically, by applicable kingdom, and by workflow type.
+    - `index.md` - The home/landing page for our documentation.
+
+### Adding a Page for a New Workflow {#new-page}
+
+If you are adding a new workflow, there are a number of things to do in order to include the page in the documentation:
+
+1. Add a page with the title of the workflow to appropriate subdirectory in `docs/workflows/`. Feel free to use the template found in the `assets/` folder.
+2. Collect the following information for your new workflow:
+     - Workflow Name - Link the name with a relative path to the workflow page in appropriate `docs/workflows/` subdirectory
+     - Workflow Description - Brief description of the workflow
+     - Applicable Kingdom - Options: "Any taxa", "Bacteria", "Mycotics", "Viral"
+     - Workflow Level (_on Terra_) - Options: "Sample-level", "Set-level", or neither
+     - Command-line compatibility - Options: "Yes", "No", and/or "Some optional features incompatible"
+     - The version where the last known changes occurred (likely the upcoming version if it is a new workflow)
+     - Link to the workflow on Dockstore (if applicable) - Workflow name linked to the information tab on Dockstore.
+3. Format this information in a table.
+4. Copy the previously gathered information to ==**ALL THREE**== overview tables in `docs/workflows_overview/`:
+     - `workflows_alphabetically.md` - Add the workflow in the appropriate spot based on the workflow name.
+     - `workflows_kingdom.md` - Add the workflow in the appropriate spot(s) based on the kingdom(s) the workflow is applicable to. Make sure it is added alphabetically within the appropriate subsection(s).
+     - `workflows_type.md` - Add the workflow in the appropriate spot based on the workflow type. Make sure it is added alphabetically within the appropriate subsection.
+5. Copy the path to the workflow to ==**ALL**== of the appropriate locations in the `mkdocs.yml` file (under the `nav:` section) in the main directory of this repository. These should be the exact same spots as in the overview tables but without additional information. This ensures the workflow can be accessed from the navigation sidebar.
diff --git a/docs/overrides/main.html b/docs/overrides/main.html
@@ -6,8 +6,3 @@
     <strong>Click here to go to the latest version release.</strong>
   </a>
 {% endblock %}
-
-
-{% block announce %}
-    <center>🏗️ I'm under construction! Pardon the dust while we remodel! 👷</center>
-{% endblock %}
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -200,7 +200,6 @@ div.searchable-table input.table-search-input {
   color: #000;
   border: 1px solid #E0E1E1;
 }
-
 [data-md-color-scheme="light"] div.searchable-table input.table-search-input::placeholder {
   color: #888;
   font-style: italic;
@@ -212,7 +211,6 @@ div.searchable-table input.table-search-input {
   color: #fff;
   border: 1px solid #373B40;
 }
-
 [data-md-color-scheme="slate"] div.searchable-table input.table-search-input::placeholder {
   color: #bbb;
   font-style: italic;