docs: revise #32

Author: oesteban

docs/contributing_tutorials/adding_a_new_template.rst

@@ -1,24 +1,24 @@
+.. _adding-new-template:
+
 Creating a new template space
-###############################################
+=============================
 
-Who is this tutorial for
-============================
+.. admonition :: Who is this tutorial for?
 
-First, this is intended for those wishing to add templates to TemplateFlow.
-Second, this is for people who want to add a template directory that does not already exists.
-TemplateFlow consists of multiple templates sorted by the space the template is in.
-This tutorial tells you how to add a new template space.
+    First, this is intended for those wishing to add templates to TemplateFlow.
+    Second, this is for people who want to add a template directory that does not already exists.
+    TemplateFlow consists of multiple templates sorted by the space the template is in.
+    This tutorial tells you how to add a new template space.
 
-If the space for you template already exists, then you should follow the tutorial: :ref: `uploading_to_existing_templates`.
+    If the space for you template already exists, then you should follow the tutorial: :ref:`upload-to-existing`.
 
-This tutorial assumes you have done all the steps in the preceding tutorial: :ref: `prerequisites_to_contributing`.
+    This tutorial assumes you have done all the steps in the preceding tutorial: :ref:`prerequisites-contributing`.
 
-**Note** at present, this tutorial will require writing access to the TemplateFlow repo.
-If you do not have access here, it may be best to open up an issue asking for a template space to be created.
+    **Note** at present, this tutorial will require writing access to the TemplateFlow repo.
+    If you do not have access here, it may be best to open up an issue asking for a template space to be created.
 
 Step 1: create a new dataset
-=============================
-
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 First make sure you are in your local templateflow directory.
 If you do not have a local templateflow copy, run:
 
@@ -33,31 +33,30 @@ Finally, write a description of your template.
 
 .. code-block:: bash
 
-    TEMPALTENAME='tpl-test'
+    TEMPLATENAME='tpl-test'
     GITHUBUSERNAME='yourusername'
-    TEMPALTEDESCRIPTION="This is a test template"
+    TEMPLATEDESCRIPTION="This is a test template"
     GITHUBREPO='templateflow'
 
-At the moment, always keep templateflow as GITHUBREPO, this may be changed in the future.
+At the moment, always keep templateflow as ``GITHUBREPO``, this may be changed in the future.
 
 With these variables set you can then run the following code with no modifications:
 
 .. code-block:: bash
 
-    datalad create -d . -D "$TEMPALTEDESCRIPTION" $TEMPALTENAME
-    cd $TEMPALTENAME
-    datalad create-sibling-github --github-organization $GITHUBREPO --github-login $GITHUBUSERNAME --access-protocol ssh $TEMPALTENAME
+    datalad create -d . -D "$TEMPLATEDESCRIPTION" $TEMPLATENAME
+    cd $TEMPLATENAME
+    datalad create-sibling-github --github-organization $GITHUBREPO --github-login $GITHUBUSERNAME --access-protocol ssh $TEMPLATENAME
     cd ..
-    sed -i -e "s/url = .\/$TEMPALTENAME/url = https:\/\/github.com\/$GITHUBREPO\/$TEMPLATENAME/g" .gitmodules
+    sed -i -e "s/url = .\/$TEMPLATENAME/url = https:\/\/github.com\/$GITHUBREPO\/$TEMPLATENAME/g" .gitmodules
     datalad save -m "set the github repo url for new template ``$TEMPLATENAME``"
     datalad publish
 
 You will be asked to enter your github username and password while running this code.
 
 Explanation of above code
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-After running, this code will create an empty datalad folder called ``tpl-test`` (or whatever TEMPLATENAME is set to).
+.........................
+After running, this code will create an empty datalad folder called ``tpl-test`` (or whatever ``TEMPLATENAME`` is set to).
 It will then change into that directory, upload the template to github.
 It will then return to the templateflow directory.
 
@@ -77,13 +76,12 @@ with:
             path = tpl-test
             url = https://github.com/templateflow/tpl-test
 
-I.e. it adds a full url link to the.
+I.e., it adds a full url link to the.
 The final two lines upload this change.
 
 Step 2: Add a template_description.json
-========================================
-
-Within this directory we place a template_description.json which is needed in all templates.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Within this directory we place a ``template_description.json`` which is needed in all templates.
 The json file contains the following:
 
 .. code-block:: json
@@ -109,5 +107,5 @@ The json file contains the following:
         }
     }
 
-Add all the necessary information into the .json file.
+Add all the necessary information into the ``.json`` file.
 Then open a pull request on github to submit this information.

docs/contributing_tutorials/prerequisites_to_contributing.rst

@@ -1,69 +1,72 @@
+.. _prerequisites-contributing:
 
 Prerequisites to contributing templates to TemplateFlow
-############################################################
+=======================================================
 
-Who is this tutorial for?
-=================================
+.. admonition :: Who is this tutorial for?
 
-Have a template that you would like to see on TemplateFlow? Great!
-Contributions are welcome.
-This document goes through some of the prerequisites needed to submit a template.
-Once you have these prerequisites achieved.
+	Have a template that you would like to see on TemplateFlow? Great!
+	Contributions are welcome.
+	This document goes through some of the prerequisites needed to submit a template.
+	Once you have these prerequisites achieved.
 
 Are you allowed to share the template?
-==========================================
-
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Templates have a licence which specifies the terms that they can be shared.
 TemplateFlow can only include templates that allow for redistribution.
-It is okay if the template requires attribution, but you need to make sure to add the attribution information.
+It is okay if the template requires attribution, but you need to make sure to
+add the attribution information into the ``template_description.json`` file.
 
 What type of contribution are you making?
-============================================
-
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 There are three different types of contributions you can make to TemplateFlow.
 
-**A new template space**.
-This contribution involves adding a new space that does not currently exist.
-Let us say you have made a new pediatric space that you transform your images to; this would be a new template space.
-All the different MNI templates are each considered their own template space.
-Currently this requires writing permissions to the TemplateFlow repo.
-For now, if you do not have access open up an issue in the templateflow repo to say which template spaces should be added.
+A new template space
+    This contribution involves adding a new space that does not currently exist.
+    Let us say you have made a new pediatric space that you transform your images to; this would be a new template space.
+    All the different MNI templates are each considered their own template space.
+    Currently this requires writing permissions to the TemplateFlow repo.
+    For now, if you do not have access open up an issue in the templateflow repo
+    to say which template spaces should be added.
 
-**Nifti images within an existing template space**.
-This contribution involves adding to a template space that currently exists.
-An example of this would be adding a nifti file that is an atlas.
-You need to know which template space your atlas is in (Note: there are multiple MNI spaces).
+NIfTI images within an existing template space
+    This contribution involves adding to a template space that currently exists.
+    An example of this would be adding a nifti file that is an atlas.
+    You need to know which template space your atlas is in (Note: there are multiple MNI spaces).
 
-**Meta information**.
-This contribution involves additional information about existing templates.
-These will generally be in .json or .tsv files.
-There are also transform files which help translate between templates.
+Meta information
+    This contribution involves additional information about existing templates.
+    These will generally be in ``.json`` or ``.tsv`` files.
+    There are also transform files which help translate between templates.
 
 There are tutorials for each of these three different types of contributions.
 
 Prerequisites for uploading nifti files
-=====================================================
-
-Aside from typical requirements (python3, git, pip), some prerequisites need addressing before you can upload a template (i.e. any image file).
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Aside from typical requirements (Python, git, pip), some prerequisites need addressing
+before you can upload a template (i.e. any image file).
 
-1. Getting access to the OSF repository. Create an issue stating you would like to access to the OSF repo. You need an account at: `osf.io <https://osf.io>`_
+1. Getting access to the OSF repository.
+   Create an issue stating you would like to access to the OSF repo.
+   You need an account at: `osf.io <https://osf.io>`__.
 2. Download the OSF client: ``pip install osfclient``.
-3. Install `DataLad <https://www.datalad.org>`_. See the `installation page <https://www.datalad.org/get_DataLad.html>`_ for more details.
-4. You also need TemplateFlows DataLad/osf tools. To install these type in a terminal: ``pip install git+https://github.com/TemplateFlow/DataLad-osf``.
+3. Install `DataLad <https://www.datalad.org>`_.
+   See the `installation page <https://www.datalad.org/get_DataLad.html>`_ for more details.
+4. You also need TemplateFlow's DataLad/OSF tools.
+   To install these type in a terminal: ``pip install git+https://github.com/TemplateFlow/DataLad-osf``.
 
 After installing these tools, you are ready to upload a template.
 
-If you only plan to contribute metadata (e.g. json files and tsv files), then these three steps are not needed.
+If you only plan to contribute metadata (e.g. JSON files and TSV files), then these three steps are not needed.
 
 Initializing the TemplateFlow OSF directory
-==================================================
-
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Once you have the prerequisites set up, you can initialize the OSF directory onto your computer.
 
 In a new directory type:
 
 .. code-block:: bash
-    
+
     osf init
 
 This will prompt you for your username and TemplateFlow project number.

docs/contributing_tutorials/uploading_to_existing_template.rst

@@ -1,34 +1,33 @@
-Uploading files to an existing template space
-###############################################
-
-Who is this tutorial for
-============================
+.. _upload-to-existing:
 
-First, this is intended for those wishing to upload templates to TemplateFlow.
-Second, this is for people who want to add to a template directory that already exists.
-TemplateFlow consists of multiple templates sorted by the space the template is in.
+Uploading files to an existing template space
+=============================================
 
-If the space for you template does not exist, then you should follow this tutorial: :ref: `adding_a_new_template`.
+.. admonition :: Who is this tutorial for?
 
-This tutorial assumes you have done all the steps in the preceding tutorial: :ref: `prerequisites_to_contributing`.
+    First, this is intended for those wishing to upload templates to TemplateFlow.
+    Second, this is for people who want to add to a template directory that already exists.
+    TemplateFlow consists of multiple templates sorted by the space the template is in.
+    If the space for you template does not exist, then you should follow :ref:`adding-new-template`.
+    This tutorial assumes you have done all the steps in the preceding tutorial:
+    :ref:`prerequisites-contributing`.
 
 Big picture
-===============
-
-Image files (e.g. nifti files) are hosted on OSF.
-All other information (e.g. tsv, json files) will be hosted on github as regular files.
+~~~~~~~~~~~
+Image files (e.g. NIfTI files) are hosted on OSF.
+All other information (e.g. TSV, JSON files) will be hosted on github as regular files.
 
 When you use TemplateFlow, the images are only downloaded when they are needed.
 This can be done with DataLad, DataLad tracks a dataset and only downloads files when they are needed.
-You can read more about DataLad `here <https://www.datalad.org>`_.
+You can read more about DataLad `here <https://www.datalad.org>`__.
 
 Thus, when uploading to an existing template, there are two different steps:
 
 1. You need to place them on the OSF server.
 2. you need to tell DataLad about the new items so the Github repo can track the new files.
 
 Step 1: Placing the template on the OSF server
-================================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Go to the TemplateFlow directory you previously initialized.
 Place the file you want to upload in directory and give them appropriate .
@@ -51,11 +50,10 @@ If you want to upload multiple images (let us say we have multiple atlases), use
 
 And this will iteratively upload all instances of the atlas to OSF.
 
-Step 2: Telling Datalad where the files are
-================================================
-
-Github is using Datalad to track the files.
-You need to tell Datalad where the new files are.
+Step 2: Telling DataLad where the files are
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Github is using DataLad to track the files.
+You need to tell DataLad where the new files are.
 
 To do this, run the following python script, changing the tqo required variables:
 
@@ -123,8 +121,8 @@ Then you add the new urls to DataLad. Add a message
     datalad addurls new_files.csv '{link}' '{name}' --message 'My test atlases'
     datalad publish
 
-Example script when subdirectories are presents
-================================================
+Example script when subdirectories are present
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: python
 
@@ -167,4 +165,4 @@ Example script when subdirectories are presents
                         link = subitem['links']['download']
                         path = subitem['attributes']['materialized']
                         hits.append(','.join((name, link)))
-    Path(output_filename).write_text('\n'.join(hits))
+    Path(output_filename).write_text('\n'.join(hits))

docs/index.rst

@@ -9,6 +9,8 @@ Contents
 .. toctree::
     :maxdepth: 3
 
+    naming
+    tutorials
     api/templateflow
 
 What's new

docs/templateflow_naming.rst renamed to docs/naming.rst

@@ -1,16 +1,14 @@
 
 TemplateFlow Naming
-===========================
+===================
 
-Who is this tutorial for?
-=================================
+.. admonition :: Who is this tutorial for?
 
-Anyone trying to understand the naming structure in TemplateFlow.
+	Anyone trying to understand the naming structure in TemplateFlow.
 
 Naming information
-===========================
-
-TemplateFlow generally follows the `BIDS naming structure <https://bids-specification.readthedocs.io/en/derivatives/>`_, but has a few deviations (e.g. the tpl key).
+~~~~~~~~~~~~~~~~~~
+TemplateFlow generally follows the `BIDS naming structure <https://bids-specification.readthedocs.io/en/derivatives/>`__, but has a few deviations (e.g. the ``tpl`` key).
 Here we outline the most common names that are found in TemplateFlow.
 
 Common key names using in TemplateFlow:
@@ -48,10 +46,7 @@ Extension    Description
 .h5          Transform file
 ==========   =======
 
-Thus a template with the following name:
-
-``tpl-test_res-01_atlas-myatlas_desc-200nodes_dseg.nii.gz``
-
-This would be a nifti image containing discrete segmentation of "myatlas" which contains 200nodes.
-And it is in the template space "test". 
+Thus a template with the following name: ``tpl-test_res-01_atlas-myatlas_desc-200nodes_dseg.nii.gz``
+would be a NIfTI image containing discrete segmentation of "myatlas" which contains 200nodes.
+And it is in the template space "test".
 The resolution information will be found in the dataset_description.json file under '01'.

docs/tutorials.rst

@@ -0,0 +1,14 @@
+.. include:: links.rst
+
+Publishing in TemplateFlow
+==========================
+Tutorials demonstrating how to upload new template resources to
+TemplateFlow.
+
+.. toctree::
+    :glob:
+    :maxdepth: 3
+
+    contributing_tutorials/prerequisites_to_contributing
+    contributing_tutorials/adding_a_new_template
+    contributing_tutorials/uploading_to_existing_template