Merge branch 'hotfix/1.12.1'

.gitignore

@@ -1,2 +1,3 @@
 docs/_build
-*.DS_Store
+*.DS_Store
+*.pyc

README.md

@@ -1,23 +1,31 @@
 # Dockstore Documentation
 
-Dockstore is using [Read the Docs](https://readthedocs.org/) for documentation!
+Dockstore is using [Read the Docs](https://readthedocs.org/) for documentation! Please take a look at [our style guide](./style-guide.md) to learn about our approach to documentation.
 
 Below are some tips for setting up the documentation locally and updating the code.
 
 ## Setting up locally
 
-Install pip dependencies (Requires Python)
+Install pip dependencies (Requires Python 3)
 `pip install -r requirements.txt`
 
 Go to the docs directory
 `cd docs`
 
-Generate the HTML
+Generate the HTML to generate HTML pages in a new folder called `_build`
 `make html`
 
 Check for broken links
 `make linkcheck`
 
-Open the _build/html/index.html in your browser!
+Open the `_build/html/index.html` in your browser!
 
-Developer Docs: https://wiki.oicr.on.ca/display/DOC/Read+The+Docs 
+OICR affilates can view additional developer docs here: https://wiki.oicr.on.ca/display/DOC/Read+The+Docs 
+
+## Writing/Maintaining docs
+Most of our docs are written in RST. A handful are written are in markdown. Both the RST and markdown documents will be rendered as HTML using the Python-based documentation manager Sphinx.
+
+Most of our docs can be maintained by modifying individual RST and MD files directly. There are a few exceptions:
+* When creating a new page, it must exist on the table of contents (`toctree`) which forms the sidebar on the left — in most cases this requires adding a new entry to index.rst
+* dictionary.rst is generated from entries in `docs/_attic/glossary_entries.py` by `docs/_attic/glossary_generator.py` in order to easily handle the complexities of large RST documents — dictionary.rst is regenerated upon every `make` command (changes will not appear in git unless `docs/_attic/glossary_entries.py` is modified), but this regeneration can also be called explictly with `make glossary`
+* Certain doi.org links, plus any images that link to internal documents, must have those links added to `linkcheck_ignore` in conf.py

docs/Makefile

@@ -11,9 +11,14 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+glossary:
+	echo "\033[1mGenerating dictionary.rst...\033[0m"
+	python _attic/glossary_generator.py
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
+	make glossary
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_attic/glossary_entries_list_dynamic.txt

@@ -0,0 +1,82 @@
+DO NOT EDIT THIS FILE. This file is autogenerated from _attic/glossary_generator.py, update that instead.
+.dockstore.yml
+AGC
+Amazon Genomics CLI
+AnVIL Project
+API
+AWS
+BD Catalyst
+BDC
+BioData Catalyst
+Cancer Genomics Cloud
+categories
+CGC
+CLI
+cloud computing
+collection
+Common Workflow Language
+container
+Cromwell
+CWL
+DAG
+descriptor file
+Docker
+Docker container
+Docker image
+Dockerfile
+Dockstore CLI
+Dockstore GitHub App
+DOI
+DS-I Africa
+EC2
+egress
+eLwazi
+entry
+faceted search
+FAIR
+GA4GH
+Galaxy
+Galaxy workflow
+GCP
+Gen3
+GitHub App registration
+GitHub App tool
+GitHub App workflow
+immutable
+interoperable
+JSON
+Jupyter
+kernel
+Kids First
+labels
+launch with
+layer
+legacy registration
+legacy tool
+legacy workflow
+NCI
+NCPI
+Nextflow
+NFL
+NHGRI
+NHLBI
+NIH
+OICR
+ORCID
+organization
+parameter file
+preemptible
+Seven Bridges
+Spot Instance
+Task Execution Service
+Terra
+TES
+tool
+UCSC
+VM
+WDL
+WES
+workflow
+Workflow Description Language
+Workflow Execution Service
+YAML

docs/_attic/glossary_generator.py

@@ -0,0 +1,26 @@
+#  This script is run using `make glossary`, and generates glossary.rst
+# (or whatever you set glossary_outfile to). 
+
+
+from glossary_entries import *  # imports all the entries from glossary_entries.py as GlossEntry objects
+from glossarpy.GreatGloss import GreatGloss
+from glossarpy.GlossEntry import GlossEntry
+import gc  # gc = garbage collector; we can use this to get instances of particular objects
+import os  # used to delete old versions of glossary_outfile and glossary_outfile
+
+glossary_outfile = "dictionary.rst"  # this one gets rendered
+contents_outfile = "_attic/glossary_entries_list_dynamic.txt"  # does not get rendered, just for quick reference
+
+try:
+    os.remove(glossary_outfile)
+    os.remove(contents_outfile)
+except OSError:
+    pass
+
+dockstore_dictionary = GreatGloss("Dockstore Dictionary")
+for glossary_object in gc.get_objects():
+    if isinstance(glossary_object, GlossEntry):
+        dockstore_dictionary.add_entry(glossary_object)
+dockstore_dictionary.sort_entries()
+dockstore_dictionary.write_toc(contents_outfile, format="txt", skipSource=False, sourcefile=__file__)
+dockstore_dictionary.write_glossary(glossary_outfile, sourcefile=__file__)

docs/_attic/readme.md

@@ -0,0 +1,9 @@
+# Attic
+
+This dusty room houses the following:
+
+* Outdated documentation pages
+* Materials used for generating images or tables
+* A script for generating the glossary
+
+There's nothing particularly secret in here, but nothing in this folder (including this readme) should be directly rendered as-is on docs.dockstore.org, although the files/images they generate might be.

docs/assets/images/square/table_of_square_icons.html → docs/_attic/table_of_square_icons.html

@@ -18,13 +18,13 @@ <h2>This document generates the image used on our index page, specifically the "
     <tr></tr>
     <tr></tr>
     <tr>
-      <td>&#xA0;&#xA0;&#xA0;<img src="anvil_square.png" width="50">&#xA0;&#xA0;&#xA0;</td>
-      <td>&#xA0;&#xA0;&#xA0;<img src="cavatica_square.png" width="50">&#xA0;&#xA0;&#xA0;</td>
-      <td>&#xA0;&#xA0;&#xA0;<img src="cgc_square.png" width="50">&#xA0;&#xA0;&#xA0;</td>
-      <td>&#xA0;&#xA0;&#xA0;<img src="dnanexus_square.png" width="50">&#xA0;&#xA0;&#xA0;</td>
-      <td>&#xA0;&#xA0;&#xA0;<img src="galaxy_square.png" width="50">&#xA0;&#xA0;&#xA0;</td>
-      <td>&#xA0;&#xA0;&#xA0;<img src="nextflowtower_square.png" width="50">&#xA0;&#xA0;&#xA0;</td>
-      <td>&#xA0;&#xA0;&#xA0;<img src="../affiliations/terra.png" width="50">&#xA0;&#xA0;&#xA0;</td>
+      <td>&#xA0;&#xA0;&#xA0;<img src="../assets/images/square/anvil_square.png" width="50">&#xA0;&#xA0;&#xA0;</td>
+      <td>&#xA0;&#xA0;&#xA0;<img src="../assets/images/square/cavatica_square.png" width="50">&#xA0;&#xA0;&#xA0;</td>
+      <td>&#xA0;&#xA0;&#xA0;<img src="../assets/images/square/cgc_square.png" width="50">&#xA0;&#xA0;&#xA0;</td>
+      <td>&#xA0;&#xA0;&#xA0;<img src="../assets/images/square/dnanexus_square.png" width="50">&#xA0;&#xA0;&#xA0;</td>
+      <td>&#xA0;&#xA0;&#xA0;<img src="../assets/images/square/galaxy_square.png" width="50">&#xA0;&#xA0;&#xA0;</td>
+      <td>&#xA0;&#xA0;&#xA0;<img src="../assets/images/square/nextflowtower_square.png" width="50">&#xA0;&#xA0;&#xA0;</td>
+      <td>&#xA0;&#xA0;&#xA0;<img src="../assets/images/affiliations/terra.png" width="50">&#xA0;&#xA0;&#xA0;</td>
     </tr>
     <tr>
       <td><center>AnVIL</center></td>

docs/advanced-topics/docker-alternatives.rst

@@ -7,7 +7,7 @@ Docker Alternatives
 In some situations using Docker may be impractical because it requires all users to have root access.
 Several alternatives have been developed to make it possible to run rootless containers, including
 `Singularity <https://sylabs.io/docs/>`_ and 
-`rootless Docker <https://engineering.docker.com/2019/02/experimenting-with-rootless-docker/>`_.
+`rootless Docker <https://www.docker.com/blog/experimenting-with-rootless-docker/>`_.
 While Dockstore uses Docker by default, if necessary it may be possible to run your workflows with one
 of these alternatives. Because the call to Docker or an alternative is made by the workflow runner, usually cwltool
 or Cromwell, and not Dockstore directly, the difficulty of configuring a Docker alternative depends on the workflow

docs/assets/images/square/readme.txt

@@ -0,0 +1 @@
+Some of these images are rendered using an HTML document in the attic folder.

docs/assets/templates/template.rst

@@ -9,6 +9,7 @@ Not sure if you are working with a workflow, a tool, or a service? :doc:`Check o
 
 Tips and tricks
 ---------------
+* This form of registration is only available to workflows, tools, and services that are hosted on GitHub
 * Make sure your file is saved as ``.dockstore.yml``, not ``dockstore.yml`` or ``.dockstore.yaml``
 * Put the .dockstore.yml file in the top of your repo or inside ``.github/``
 * The first line of a .dockstore.yml file references the version of .dockstore.yml syntax being used, not the version/tag of the workflow/tool/service it describes
@@ -17,7 +18,7 @@ Tips and tricks
 
 Examples of the filters field
 -----------------------------
-* The ``filters:`` field allows for limiting which branches and tags appear on a Dockstore entry. Regex can be used here.
+* The ``filters:`` field allows for limiting which GitHub `tags <https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/managing-commits/managing-tags>`_ and `branches <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches>`_ appear on a Dockstore entry. Regex can be used here.
 * You can use this regex pattern to include all tags but no branches:
 
 .. code:: yaml

docs/conf.py

@@ -87,7 +87,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store', '_attic/*']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None