diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 0481cdc1..b6fb85c9 100644 --- a/.github/workflows/docs.yml +++ b/.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 diff --git a/README.md b/README.md index 6b5ff122..6f35bfe9 100644 --- a/README.md +++ b/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): diff --git a/docs/Makefile b/docs/Makefile index 5942c131..22777c27 100644 --- a/docs/Makefile +++ b/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) diff --git a/docs/list_softwares.py b/docs/list_softwares.py new file mode 100644 index 00000000..0b0d5efd --- /dev/null +++ b/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) diff --git a/docs/user_guide/add_template.rst b/docs/user_guide/add_template.rst index d5f562a6..a02c1534 100644 --- a/docs/user_guide/add_template.rst +++ b/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. diff --git a/docs/user_guide/examples.rst b/docs/user_guide/examples.rst index 638f3fff..62f8ea3a 100644 --- a/docs/user_guide/examples.rst +++ b/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 `_ +- `ants `_ +- `cat12 `_ +- `convert3d `_ +- `dcm2niix `_ +- `freesurfer `_ +- `fsl `_ +- `jq `_ +- `matlabmcr `_ +- `minc `_ +- `miniconda `_ +- `mricron `_ +- `mrtrix3 `_ +- `ndfreeze `_ +- `neurodebian `_ +- `niftyreg `_ +- `petpvc `_ +- `spm12 `_ +- `vnc `_ + +.. INSERT LIST END + +The commands generate Dockerfiles. To generate Singularity recipes, simply replace .. code-block:: bash diff --git a/neurodocker/cli/tests/sample-template-jq.yaml b/neurodocker/cli/tests/sample-template-jq.yaml index 1949af45..29c3808b 100644 --- a/neurodocker/cli/tests/sample-template-jq.yaml +++ b/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: diff --git a/neurodocker/reproenv/schemas/template.json b/neurodocker/reproenv/schemas/template.json index 8064609c..1181b728 100644 --- a/neurodocker/reproenv/schemas/template.json +++ b/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": [ diff --git a/neurodocker/reproenv/tests/sample-template-jq.yaml b/neurodocker/reproenv/tests/sample-template-jq.yaml index a54de472..0f5bac02 100644 --- a/neurodocker/reproenv/tests/sample-template-jq.yaml +++ b/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: diff --git a/neurodocker/reproenv/tests/test_renderers_docker.py b/neurodocker/reproenv/tests/test_renderers_docker.py index e033214f..3a2fc678 100644 --- a/neurodocker/reproenv/tests/test_renderers_docker.py +++ b/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"}, diff --git a/neurodocker/reproenv/tests/test_renderers_singularity.py b/neurodocker/reproenv/tests/test_renderers_singularity.py index ceb560e4..5a4b0b32 100644 --- a/neurodocker/reproenv/tests/test_renderers_singularity.py +++ b/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"}, diff --git a/neurodocker/reproenv/tests/test_state.py b/neurodocker/reproenv/tests/test_state.py index a201a92e..ae3bbf55 100644 --- a/neurodocker/reproenv/tests/test_state.py +++ b/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"}, diff --git a/neurodocker/reproenv/tests/test_template.py b/neurodocker/reproenv/tests/test_template.py index 30f0b186..458f65d3 100644 --- a/neurodocker/reproenv/tests/test_template.py +++ b/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) diff --git a/neurodocker/templates/_header.yaml b/neurodocker/templates/_header.yaml index ac18125c..9f0e293b 100644 --- a/neurodocker/templates/_header.yaml +++ b/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: diff --git a/neurodocker/templates/afni.yaml b/neurodocker/templates/afni.yaml index 717986f8..ef68e991 100644 --- a/neurodocker/templates/afni.yaml +++ b/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: diff --git a/neurodocker/templates/ants.yaml b/neurodocker/templates/ants.yaml index ad50a89a..5bfb15b4 100644 --- a/neurodocker/templates/ants.yaml +++ b/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: diff --git a/neurodocker/templates/cat12.yaml b/neurodocker/templates/cat12.yaml index 2eb85ef9..cc883bb2 100644 --- a/neurodocker/templates/cat12.yaml +++ b/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: diff --git a/neurodocker/templates/convert3d.yaml b/neurodocker/templates/convert3d.yaml index a531415e..f02b1edb 100644 --- a/neurodocker/templates/convert3d.yaml +++ b/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: diff --git a/neurodocker/templates/dcm2niix.yaml b/neurodocker/templates/dcm2niix.yaml index f80e25d4..7d05b319 100644 --- a/neurodocker/templates/dcm2niix.yaml +++ b/neurodocker/templates/dcm2niix.yaml @@ -1,6 +1,7 @@ # Instructions to install dcm2niix. name: dcm2niix +url: https://www.nitrc.org/plugins/mwiki/index.php/dcm2nii:MainPage binaries: arguments: required: diff --git a/neurodocker/templates/freesurfer.yaml b/neurodocker/templates/freesurfer.yaml index 76f7f064..d076f543 100644 --- a/neurodocker/templates/freesurfer.yaml +++ b/neurodocker/templates/freesurfer.yaml @@ -1,6 +1,7 @@ # Instructions to install FreeSurfer. name: freesurfer +url: https://surfer.nmr.mgh.harvard.edu/ binaries: arguments: required: diff --git a/neurodocker/templates/fsl.yaml b/neurodocker/templates/fsl.yaml index 8e284842..4d88e1b7 100644 --- a/neurodocker/templates/fsl.yaml +++ b/neurodocker/templates/fsl.yaml @@ -5,11 +5,11 @@ # the relevant license. # ***************************************************************************** # -# Website: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/ # License: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Licence # Available Versions: https://fsl.fmrib.ox.ac.uk/fsldownloads/manifest.json name: fsl +url: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/ alert: FSL is non-free. If you are considering commercial use of FSL, please consult the relevant license(s). binaries: arguments: diff --git a/neurodocker/templates/jq.yaml b/neurodocker/templates/jq.yaml index 0f0dbe90..4ab464df 100644 --- a/neurodocker/templates/jq.yaml +++ b/neurodocker/templates/jq.yaml @@ -1,6 +1,7 @@ # Sample template. Installs `jq` (a JSON parser) from binaries or from source. name: jq +url: https://jqlang.github.io/jq/ binaries: arguments: required: diff --git a/neurodocker/templates/matlabmcr.yaml b/neurodocker/templates/matlabmcr.yaml index ec81a3d3..7402aa61 100644 --- a/neurodocker/templates/matlabmcr.yaml +++ b/neurodocker/templates/matlabmcr.yaml @@ -1,9 +1,8 @@ --- # Instructions to install MATLAB Compiler Runtime. -# -# Website: https://www.mathworks.com/products/compiler/matlab-runtime.html name: matlabmcr +url: https://www.mathworks.com/products/compiler/matlab-runtime.html binaries: arguments: required: diff --git a/neurodocker/templates/minc.yaml b/neurodocker/templates/minc.yaml index d57da09e..6ab50a4e 100644 --- a/neurodocker/templates/minc.yaml +++ b/neurodocker/templates/minc.yaml @@ -1,11 +1,10 @@ # Instructions to install MINC toolkit v2. # -# Repository: https://github.com/BIC-MNI/minc-toolkit-v2 -# # Instructions: http://bic-mni.github.io/#on-debianubuntu # The Debian packages are unpacked for yum based distributions as well name: minc +url: https://github.com/BIC-MNI/minc-toolkit-v2 binaries: arguments: required: diff --git a/neurodocker/templates/miniconda.yaml b/neurodocker/templates/miniconda.yaml index 770a33c5..b6bd87d9 100644 --- a/neurodocker/templates/miniconda.yaml +++ b/neurodocker/templates/miniconda.yaml @@ -1,6 +1,7 @@ # Instructions to install Miniconda. name: miniconda +url: https://docs.conda.io/projects/miniconda/en/latest/ binaries: urls: latest: https://repo.continuum.io/miniconda/Miniconda3-{{ self.version }}-Linux-x86_64.sh diff --git a/neurodocker/templates/mricron.yaml b/neurodocker/templates/mricron.yaml index 8ca7dbb1..d1f0808c 100644 --- a/neurodocker/templates/mricron.yaml +++ b/neurodocker/templates/mricron.yaml @@ -1,8 +1,7 @@ # Instructions to install MRIcron. -# -# Repository: https://github.com/neurolabusc/MRIcron name: mricron +url: https://github.com/neurolabusc/MRIcron binaries: arguments: required: diff --git a/neurodocker/templates/mrtrix3.yaml b/neurodocker/templates/mrtrix3.yaml index 4d8345d2..9b196bce 100644 --- a/neurodocker/templates/mrtrix3.yaml +++ b/neurodocker/templates/mrtrix3.yaml @@ -1,6 +1,7 @@ # Instructions to install MRtrix3. name: mrtrix3 +url: https://www.mrtrix.org/ binaries: arguments: required: diff --git a/neurodocker/templates/ndfreeze.yaml b/neurodocker/templates/ndfreeze.yaml index 95882248..18618b51 100644 --- a/neurodocker/templates/ndfreeze.yaml +++ b/neurodocker/templates/ndfreeze.yaml @@ -1,6 +1,7 @@ # Instructions to run `nd_freeze` in NeuroDebian images. name: ndfreeze +url: https://neuro.debian.net/pkgs/neurodebian-freeze.html # not actually source, but we have a choice between binaries and source. Using binaries # requires the urls property. source: diff --git a/neurodocker/templates/neurodebian.yaml b/neurodocker/templates/neurodebian.yaml index 279d2706..ad5d642d 100644 --- a/neurodocker/templates/neurodebian.yaml +++ b/neurodocker/templates/neurodebian.yaml @@ -1,6 +1,7 @@ # Instructions to add NeuroDebian repositories. name: neurodebian +url: http://neuro.debian.net binaries: urls: australia: "http://neuro.debian.net/lists/{{ self.os_codename }}.au.{{ self.full_or_libre }}" diff --git a/neurodocker/templates/niftyreg.yaml b/neurodocker/templates/niftyreg.yaml index 87664ba0..54341f02 100644 --- a/neurodocker/templates/niftyreg.yaml +++ b/neurodocker/templates/niftyreg.yaml @@ -1,5 +1,6 @@ # Template for niftyreg. name: niftyreg +url: https://github.com/KCL-BMEIS/niftyreg source: arguments: required: diff --git a/neurodocker/templates/petpvc.yaml b/neurodocker/templates/petpvc.yaml index 1de920bb..4d5b42b5 100644 --- a/neurodocker/templates/petpvc.yaml +++ b/neurodocker/templates/petpvc.yaml @@ -1,8 +1,7 @@ # Instructions to install PETPVC. -# -# Repository: https://github.com/UCL/PETPVC name: petpvc +url: https://github.com/UCL/PETPVC binaries: arguments: required: diff --git a/neurodocker/templates/spm12.yaml b/neurodocker/templates/spm12.yaml index 7d5c990a..78b2cae7 100644 --- a/neurodocker/templates/spm12.yaml +++ b/neurodocker/templates/spm12.yaml @@ -1,11 +1,9 @@ # Instructions to install SPM. # -# Website: https://www.fil.ion.ucl.ac.uk/spm/ # Documentation: https://www.fil.ion.ucl.ac.uk/spm/doc/ -# TODO: - name: spm12 +url: https://www.fil.ion.ucl.ac.uk/spm/ binaries: arguments: required: diff --git a/neurodocker/templates/vnc.yaml b/neurodocker/templates/vnc.yaml index 35f110c5..deee1ac8 100644 --- a/neurodocker/templates/vnc.yaml +++ b/neurodocker/templates/vnc.yaml @@ -3,6 +3,7 @@ # Run: # vncserver -geometry 1600x1200 name: vnc +url: https://www.realvnc.com/ # Not actually source, but we do not want to provide binaries. source: arguments: