[DOC] add list of supported softwares

.github/workflows/docs.yml

@@ -18,6 +18,7 @@ jobs:
       - name: build docs
         run: |
           make -C docs cli
+          make -C docs list
           sphinx-build docs docs-build
       - name: Deploy
         uses: JamesIves/github-pages-deploy-action@v4

README.md

@@ -9,6 +9,8 @@ _Neurodocker_ is a command-line program that generates custom Dockerfiles and Si
 
 Please see our website https://www.repronim.org/neurodocker for more information.
 
+See our [list of supported software](https://www.repronim.org/neurodocker/user_guide/examples.html#supported-software)
+
 # Installation
 
 Use the _Neurodocker_ Docker image (recommended):

docs/Makefile

@@ -17,7 +17,10 @@ help:
 cli:
 	bash generate_cli_help.sh
 
+list:
+	python list_softwares.py
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile cli
+%: Makefile cli list
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/list_softwares.py

@@ -0,0 +1,36 @@
+"""Print list of software packages to be included in the documentation.
+
+Read them from the registered yml templates.
+"""
+from pathlib import Path
+
+from neurodocker.reproenv.state import registered_templates_items
+
+output_file = Path(__file__).parent / "user_guide" / "examples.rst"
+
+software = {"name": [], "url": []}
+for s in registered_templates_items():
+    if s[1]["name"] == "_header":
+        continue
+    software["name"].append(s[1]["name"])
+    software["url"].append(s[1]["url"])
+
+with open(output_file, "r") as f:
+    lines = f.readlines()
+
+with open(output_file, "w") as f:
+    print_list = False
+
+    for line in lines:
+        if line.startswith(".. INSERT LIST START"):
+            print_list = True
+            f.write(line)
+            f.write("\n")
+            for s in sorted(zip(software["name"], software["url"])):
+                f.write(f"- `{s[0]} <{s[1]}>`_\n")
+            f.write("\n")
+        if line.startswith(".. INSERT LIST END"):
+            print_list = False
+
+        if not print_list:
+            f.write(line)

docs/user_guide/add_template.rst

@@ -19,6 +19,7 @@ This example installs :code:`jq`, a
     # The name of the software. This becomes the name in the template registry.
     # The CLI option would be rendered as `--jq`.
     name: jq
+    url: https://jqlang.github.io/jq/
     # An alert that is printed when using this template in the CLI.
     alert: Please be advised that this software uses
     # How to install this software from pre-compiled binaries.

docs/user_guide/examples.rst

@@ -2,7 +2,36 @@ Examples
 ========
 
 This page includes examples of using Neurodocker to build containers with popular
-neuroimaging packages. The commands generate Dockerfiles. To generate Singularity
+neuroimaging packages.
+
+Supported software
+------------------
+
+.. INSERT LIST START (will be updated automatically in ci)
+
+- `afni <https://afni.nimh.nih.gov>`_
+- `ants <http://stnava.github.io/ANTs/>`_
+- `cat12 <https://neuro-jena.github.io/cat/>`_
+- `convert3d <http://www.itksnap.org/pmwiki/pmwiki.php?n=Convert3D.Convert3D>`_
+- `dcm2niix <https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage>`_
+- `freesurfer <https://surfer.nmr.mgh.harvard.edu/>`_
+- `fsl <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/>`_
+- `jq <https://jqlang.github.io/jq/>`_
+- `matlabmcr <https://www.mathworks.com/products/compiler/matlab-runtime.html>`_
+- `minc <https://github.com/BIC-MNI/minc-toolkit-v2>`_
+- `miniconda <https://docs.conda.io/projects/miniconda/en/latest/>`_
+- `mricron <https://github.com/neurolabusc/MRIcron>`_
+- `mrtrix3 <https://www.mrtrix.org/>`_
+- `ndfreeze <https://neuro.debian.net/pkgs/neurodebian-freeze.html>`_
+- `neurodebian <http://neuro.debian.net>`_
+- `niftyreg <https://github.com/KCL-BMEIS/niftyreg>`_
+- `petpvc <https://github.com/UCL/PETPVC>`_
+- `spm12 <https://www.fil.ion.ucl.ac.uk/spm/>`_
+- `vnc <https://www.realvnc.com/>`_
+
+.. INSERT LIST END
+
+The commands generate Dockerfiles. To generate Singularity
 recipes, simply replace
 
 .. code-block:: bash

neurodocker/cli/tests/sample-template-jq.yaml

@@ -1,6 +1,7 @@
 # Sample template. Installs `jq` from binaries or from source.
 
 name: jq
+url: "some-url"
 binaries:
   arguments:
     required:

neurodocker/reproenv/schemas/template.json

@@ -3,7 +3,8 @@
   "title": "Template Schema",
   "type": "object",
   "required": [
-    "name"
+    "name",
+    "url"
   ],
   "anyOf": [
     {
@@ -21,6 +22,9 @@
     "name": {
       "type": "string"
     },
+    "url":{
+      "type": "string"
+    },
     "alert": {
       "type": "string",
       "examples": [

neurodocker/reproenv/tests/sample-template-jq.yaml

@@ -1,6 +1,7 @@
 # Sample template. Installs `jq` from binaries or from source.
 
 name: jq
+url: "some-url"
 binaries:
   arguments:
     required:

neurodocker/reproenv/tests/test_renderers_docker.py

@@ -11,6 +11,7 @@ def test_docker_renderer_add_template():
 
     d = {
         "name": "foobar",
+        "url": "some-url",
         "binaries": {
             "urls": {"1.0.0": "foobar"},
             "env": {"foo": "bar"},
@@ -64,6 +65,7 @@ def test_docker_renderer_add_template():
     # Test required arguments.
     d = {
         "name": "foobar",
+        "url": "some-url",
         "binaries": {
             "urls": {"1.0.0": "foobar"},
             "env": {"foo": "bar"},
@@ -90,6 +92,7 @@ def test_docker_renderer_add_template():
 
     d = {
         "name": "foobar",
+        "url": "some-url",
         "binaries": {
             "urls": {"1.0.0": "foobar"},
             "env": {"foo": "bar"},

neurodocker/reproenv/tests/test_renderers_singularity.py

@@ -11,6 +11,7 @@ def test_singularity_renderer_add_template():
 
     d = {
         "name": "foobar",
+        "url": "some-url",
         "binaries": {
             "urls": {"1.0.0": "foobar"},
             "env": {"foo": "bar"},
@@ -59,6 +60,7 @@ def test_singularity_renderer_add_template():
 
     d = {
         "name": "baz",
+        "url": "some-url",
         "binaries": {
             "urls": {"1.0.0": "foobar"},
             "env": {"foo": "bar"},

neurodocker/reproenv/tests/test_state.py

@@ -11,8 +11,10 @@ def test_validate_template_invalid_templates():
     with pytest.raises(exceptions.TemplateError, match="'name' is a required property"):
         _validate_template({})
 
-    with pytest.raises(exceptions.TemplateError, match="{'name': 'bar'} is not valid"):
-        _validate_template({"name": "bar"})
+    with pytest.raises(
+        exceptions.TemplateError, match="is not valid under any of the given schemas"
+    ):
+        _validate_template({"name": "bar", "url": "some-url"})
 
     # missing 'name' top-level key
     with pytest.raises(exceptions.TemplateError, match="'name' is a required property"):
@@ -28,6 +30,7 @@ def test_validate_template_invalid_templates():
         _validate_template(
             {
                 "name": 1234,
+                "url": "some-url",
                 "binaries": {"urls": {"1.0.0": "foobar.com"}, "instructions": "foobar"},
             }
         )
@@ -43,6 +46,7 @@ def test_validate_template_invalid_templates():
         _validate_template(
             {
                 "name": "foobar",
+                "url": "some-url",
                 "binaries": {
                     "urls": {"1.0.0": "foobar.com"},
                     # "instructions": "foobar",
@@ -58,6 +62,7 @@ def test_validate_template_invalid_templates():
         _validate_template(
             {
                 "name": "foobar",
+                "url": "some-url",
                 "binaries": {
                     "urls": {"1.0.0": "foobar.com"},
                     "env": {"foo": ["foo"]},
@@ -71,6 +76,7 @@ def test_validate_template_invalid_templates():
         _validate_template(
             {
                 "name": "foobar",
+                "url": "some-url",
                 "binaries": {
                     # "urls": {"1.0.0": "foobar.com"},
                     "instructions": "foobar"
@@ -89,6 +95,7 @@ def test_validate_template_invalid_templates():
         _validate_template(
             {
                 "name": "foobar",
+                "url": "some-url",
                 "binaries": {
                     "urls": {"1.0.0": "foobar.com"},
                     "instructions": "foobar",
@@ -108,6 +115,7 @@ def test_validate_template_invalid_templates():
         _validate_template(
             {
                 "name": "foobar",
+                "url": "some-url",
                 "binaries": {
                     "urls": {"1.0.0": "foobar.com"},
                     "instructions": "foobar",
@@ -134,6 +142,7 @@ def test_validate_template_invalid_templates():
         _validate_template(
             {
                 "name": "foobar",
+                "url": "some-url",
                 "source": {"urls": {"1.0.0": "foobar.com"}, "instructions": "foobar"},
             }
         )
@@ -145,6 +154,7 @@ def test_validate_template_invalid_templates():
         _validate_template(
             {
                 "name": "foobar",
+                "url": "some-url",
                 "source": {
                     # "instructions": "foobar",
                 },
@@ -159,6 +169,7 @@ def test_validate_template_invalid_templates():
         _validate_template(
             {
                 "name": "foobar",
+                "url": "some-url",
                 "source": {"env": {"foo": ["foo"]}, "instructions": "foobar"},
             }
         )
@@ -172,7 +183,11 @@ def test_validate_template_invalid_templates():
         ),
     ):
         _validate_template(
-            {"name": "foobar", "source": {"instructions": "foobar", "extra": ""}}
+            {
+                "name": "foobar",
+                "url": "some-url",
+                "source": {"instructions": "foobar", "extra": ""},
+            }
         )
 
     # extra keys in dependencies
@@ -186,6 +201,7 @@ def test_validate_template_invalid_templates():
         _validate_template(
             {
                 "name": "foobar",
+                "url": "some-url",
                 "source": {
                     "instructions": "foobar",
                     "dependencies": {"apt": [], "fakemngr": []},
@@ -202,15 +218,19 @@ def test_validate_template_valid_templates():
     _validate_template(
         {
             "name": "foobar",
+            "url": "some-url",
             "binaries": {"urls": {"v1": "foo"}, "instructions": "foobar"},
         }
     )
-    _validate_template({"name": "foobar", "source": {"instructions": "foobar"}})
+    _validate_template(
+        {"name": "foobar", "url": "some-url", "source": {"instructions": "foobar"}}
+    )
 
     # bigger templates
     _validate_template(
         {
             "name": "foobar",
+            "url": "some-url",
             "binaries": {
                 "urls": {"v1": "foo"},
                 "env": {"baz": "cat", "boo": "123"},
@@ -233,6 +253,7 @@ def test_register(tmp_path: Path):
 
     _one_test_template: types.TemplateType = {
         "name": "foobar",
+        "url": "some-url",
         "binaries": {
             "urls": {"1.0.0": "foobar.com"},
             "env": {"foo": "bar"},

neurodocker/reproenv/tests/test_template.py

@@ -6,6 +6,7 @@
 def test_template():
     d = {
         "name": "foobar",
+        "url": "some-url",
         "binaries": {
             "urls": {"v1": "foo"},
             "env": {"baz": "cat", "boo": "123"},
@@ -62,6 +63,7 @@ def test_template():
     t = template.Template(
         {
             "name": "foobar",
+            "url": "some-url",
             "binaries": {
                 "urls": {"v1": "foo"},
                 "env": {"baz": "cat", "boo": "123"},
@@ -78,6 +80,7 @@ def test_template():
     t = template.Template(
         {
             "name": "foobar",
+            "url": "some-url",
             "source": {
                 "env": {"foo": "bar"},
                 "instructions": "echo foo\n{{ self.boo }}",
@@ -197,6 +200,7 @@ def test_template_alert():
     d: types.TemplateType = {
         "alert": "This is an alert!",
         "name": "testing",
+        "url": "some-url",
         "binaries": {"urls": {"foo": "foo.baz.tar.gz"}, "instructions": "do nothing"},
     }
     tmpl = template.Template(d)

neurodocker/templates/_header.yaml

@@ -4,6 +4,7 @@
 # TODO: read this about locales http://jaredmarkell.com/docker-and-locales/
 
 name: _header
+url: "n/a"
 # Not actually source, but we do not want to provide URLs.
 source:
   dependencies:

neurodocker/templates/afni.yaml

@@ -3,6 +3,7 @@
 # TODO: consider updating the source instructions to use cmake.
 
 name: afni
+url: https://afni.nimh.nih.gov
 binaries:
   arguments:
     optional:

neurodocker/templates/ants.yaml

@@ -1,6 +1,7 @@
 # Instructions to install ANTs (https://github.com/ANTsX/ANTs)
 
 name: ants
+url: http://stnava.github.io/ANTs/
 binaries:
   arguments:
     required:

neurodocker/templates/cat12.yaml

@@ -1,10 +1,10 @@
 # Instructions to install CAT12 toolbox with SPM.
 #
-# Website: http://141.35.69.218/cat/
 # Documentation: http://www.neuro.uni-jena.de/cat12-html/cat_versions.html
 
 
 name: cat12
+url: https://neuro-jena.github.io/cat/
 binaries:
   arguments:
     required:

neurodocker/templates/convert3d.yaml

@@ -1,6 +1,7 @@
 # Instructions to install Convert3D.
 
 name: convert3d
+url: http://www.itksnap.org/pmwiki/pmwiki.php?n=Convert3D.Convert3D
 binaries:
   arguments:
     required: