Documentation update

CONTRIBUTING.rst

@@ -5,59 +5,53 @@ Contributing to BIDScoin
 Project organization
 --------------------
 
-* `bidscoin/ <./bidscoin>`__ is the main Python module where major development is happening, with main submodules being:
+* `bidscoin/ <./bidscoin>`__ - The main module with the core libraries and applications, as well as some submodules:
 
   - ``bidsapps/`` - Applications that can process BIDS or BIDS-like data folders
-  - ``cli/`` - wrappers and argument parsers bringing the BIDScoin functionality to the command line
+  - ``cli/`` - Argument parsers for generating BIDScoin manpages and Command Line Interfaces (CLI)
   - ``heuristics/`` - Pre-installed template bidsmaps
   - ``plugins/`` - Pre-installed plugins
   - ``schema/`` - Schema files from the `BIDS specifications <https://github.com/bids-standard/bids-specification/tree/master/src/schema>`__
   - ``utilities/`` -
 
-* `docs/ <./docs>`_ - The Sphynx documentation directory
-* `tests/ <./tests>`_ - helper utilities used during development, testing, and distribution of
+* `docs/ <./docs>`_ - The Sphinx `RTD <https://bidscoin.readthedocs.io>`__ documentation repository
+* `tests/ <./tests>`_ - The collection of test modules for the `CI development <https://github.com/features/actions>`__ of BIDScoin
 
-How to contribute
------------------
+How to contribute code
+----------------------
 
-The preferred way to contribute to the BIDScoin code base is
-to fork the `main repository <https://github.com/nipy/bidscoin/>`_ on GitHub.
+The preferred way to contribute to the BIDScoin code base or documentation is to fork the `main repository <https://github.com/Donders-Institute/bidscoin>`_ on GitHub. If you are unsure what that means, here is a set-up workflow you may wish to follow:
 
-If you are unsure what that means, here is a set-up workflow you may wish to follow:
+0. Fork the `project repository <https://github.com/Donders-Institute/bidscoin>`_ on GitHub, by clicking on the “Fork” button near the top of the page — this will create a personal copy of the repository.
 
-0. Fork the `project repository <https://github.com/nipy/bidscoin>`_ on GitHub, by clicking on the “Fork” button near the top of the page — this will create a copy of the repository writeable by your GitHub user.
-1. Set up a clone of the repository on your local machine and connect it to both the “official”
-   and your copy of the repository on GitHub::
+1. Set up a clone of the repository on your local machine and connect it to both the “official” and your copy of the repository on GitHub::
 
-     git clone git://github.com/nipy/bidscoin
+     git clone git://github.com/Donders-Institute/bidscoin
      cd bidscoin
      git remote rename origin official
-     git remote add origin git://github.com/YOUR_GITHUB_USERNAME/bidscoin
+     git remote add origin git://github.com/[YOUR_GITHUB_USERNAME]/bidscoin
 
 2. When you wish to start a new contribution, create a new branch::
 
-     git checkout -b topic_of_your_contribution
-
-3. When you are done making the changes you wish to contribute, record them in Git::
+     git checkout -b [topic_of_your_contribution]
 
-     git add the/paths/to/files/you/modified can/be/more/than/one
-     git commit
-
-3. Push the changes to your copy of the code on GitHub, following which Git will provide you with a link which you can click to initiate a pull request::
+3. When you are done making the changes you wish to contribute, commit and push them to GitHub::
 
+     git commit -am "[A SHORT DESCRIPTION OF THE CHANGES]"  # Run this command every time you have made a set of changes that belong together
      git push -u origin topic_of_your_contribution
 
-(If any of the above seems overwhelming, you can look up the `Git documentation <http://git-scm.com/documentation>`__ on the web.)
-
+Git will provide you with a link which you can click to initiate a pull request (if any of the above seems overwhelming, you can look up the `Git <http://git-scm.com/documentation>`__ or `GitHub <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`__ documentation on the web)
 
 Coding guidelines
 -----------------
 
 It is recommended to check that your contribution complies with the following rules before submitting a pull request:
 
-* All cli functions (i.e. functions that have an entrypoint + manpage in ``pyproject.toml``) should have informative docstrings with usage examples presented as argparse epilogues.
-* Docstrings are formatted in
-* Screens are wide nowadays, so the PEP directives for short code lines do not need to be respected
-* Because line length is not limited, multi-line readability is preferred, e.g. the vertical alignment of ``=`` operators (padded with whitespaces)
-* All tests in ``tests`` must pass
-* New code should be accompanied by new tests.
+* CLI applications (i.e. Python modules that have an entrypoint + manpage in ``pyproject.toml``) should have informative docstrings and arguments, with usage examples presented as argparse epilogues. All CLIs and plugins should be described in the Sphinx RTD documentation.
+* Docstrings are formatted in `Sphinx style <https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html>`__
+* New modules or functionality should be accompanied with type annotations and new (py)tests
+* All tests performed with `tox <https://tox.wiki>`__ must pass (python environments can be skipped, if at least one of them is checked)
+* Screens are wide nowadays, so the PEP directives for short code lines is considered outdated and does not have to be respected
+* To improve code readability, minor comments can (should) be appended at the end of the code lines they apply to
+* Horizontal space is not limited, so multi-line readability is preferred, e.g. the vertical alignment of ``=`` operators (i.e. padded horizontally with whitespaces)
+* Vertical space should not be readily wasted to promote better overviews and minimize the need for scrolling

README.rst

@@ -10,11 +10,11 @@ BIDScoin: Coin your imaging data to BIDS
 
 .. raw:: html
 
-   <img name="bidscoin-logo" src="./bidscoin/bidscoin_logo.png" height="340px" align="right" alt=" ">
+   <img name="bidscoin-logo" src="https://github.com/Donders-Institute/bidscoin/blob/master/bidscoin/bidscoin_logo.png" height="340px" align="right" alt=" ">
 
 |PyPI version| |BIDS| |PyPI - Python Version| |GPLv3| |RTD| |Tests| |DOI|
 
-BIDScoin is a user-friendly Python application suite that converts ("coins") source-level (raw) neuroimaging data sets to standardized data sets that are organized according to the Brain Imaging Data Structure (`BIDS <https://bids-specification.readthedocs.io>`__) specification. Rather than depending on complex programmatic logic for source data-type identification, BIDScoin uses a mapping approach to discover the different source data types in your repository and convert them into BIDS data types. Different runs of source data are uniquely identified by their file system properties (e.g. file name or size) and by their attributes (e.g. ``ProtocolName`` from the DICOM header). Mapping information can be pre-specified (e.g. per site), allowing BIDScoin to make intelligent first suggestions on how to classify and convert the data. While this command-line procedure exploits all information available on disk, BIDScoin presents a `Graphical User Interface (GUI) <screenshots.html>`__ for researchers to check and edit these mappings -- bringing in the missing knowledge that often exists only in their heads.
+BIDScoin is a user-friendly Python application suite that converts ("coins") source-level (raw) neuroimaging data sets to standardized data sets that are organized according to the Brain Imaging Data Structure (`BIDS <https://bids-specification.readthedocs.io>`__) specification. Rather than depending on complex programmatic logic for source data-type identification, BIDScoin uses a mapping approach to discover the different source data types in your repository and convert them into BIDS data types. Different runs of source data are uniquely identified by their file system properties (e.g. file name or size) and by their attributes (e.g. ``ProtocolName`` from the DICOM header). Mapping information can be pre-specified (e.g. per site), allowing BIDScoin to make intelligent first suggestions on how to classify and convert the data. While this command-line procedure exploits all information available on disk, BIDScoin presents a `Graphical User Interface (GUI) <./screenshots.html>`__ for researchers to check and edit these mappings -- bringing in the missing knowledge that often exists only in their heads.
 
 Data conversions are performed within plugins, such as plugins that employ `dcm2niix <https://github.com/rordenlab/dcm2niix>`__, `spec2nii <https://github.com/wtclarke/spec2nii>`__ or `nibabel <https://nipy.org/nibabel>`__.
 
@@ -41,23 +41,12 @@ Features
 
    ``** = Only Twix, SDAT/SPAR and P-file source data``
 
-::
+.. note::
 
-   Are you a Python programmer with an interest in BIDS who knows about GE and/or Philips data?
-   Are you experienced with parsing stimulus presentation log-files? Or do you have ideas to improve
-   BIDScoin or its documentation? Have you come across bugs? In any case, you are highly encouraged
-   to provide feedback or contribute to this project on https://github.com/Donders-Institute/bidscoin.
-
-Note:
------
-
-   **All source code is hosted at** `Github <https://github.com/Donders-Institute/bidscoin>`__ **and freely available under the GPL-3.0-or-later** `license <https://spdx.org/licenses/GPL-3.0-or-later.html>`__.
-
-   **The full BIDScoin documentation is hosted at** `Read the Docs <https://bidscoin.readthedocs.io>`__
-
-   **For citation and more information, see our** `BIDScoin publication <https://www.frontiersin.org/articles/10.3389/fninf.2021.770608>`__ **in Frontiers in Neuroinformatics** (`doi: 10.3389/fninf.2021.770608 <https://doi.org/10.3389/fninf.2021.770608>`__)
-
-   **Issues or questions can be posted at** `Github <https://github.com/Donders-Institute/bidscoin/issues>`__
+   * All **source code** is hosted at `Github <https://github.com/Donders-Institute/bidscoin>`__ and **freely available** under the GPL-3.0-or-later `license <https://spdx.org/licenses/GPL-3.0-or-later.html>`__.
+   * The full BIDScoin **documentation** is hosted at `Read the Docs <https://bidscoin.readthedocs.io>`__
+   * For citation and more information, see our `BIDScoin publication <https://www.frontiersin.org/articles/10.3389/fninf.2021.770608>`__ in **Frontiers in Neuroinformatics** (`doi: 10.3389/fninf.2021.770608 <https://doi.org/10.3389/fninf.2021.770608>`__)
+   * You are encouraged to **post issues or questions at** `Github <https://github.com/Donders-Institute/bidscoin/issues>`__ or `NeuroStars <https://neurostars.org/tag/bidscoin>`__
 
 .. |PyPI version| image:: https://img.shields.io/pypi/v/bidscoin?color=success
    :target: https://pypi.org/project/bidscoin
@@ -79,3 +68,12 @@ Note:
 .. |Tests| image:: https://github.com/Donders-Institute/bidscoin/actions/workflows/tests.yaml/badge.svg
    :target: https://github.com/Donders-Institute/bidscoin/actions
    :alt: Pytest results
+
+How to contribute
+-----------------
+
+Are you a Python programmer with an interest in BIDS who knows about GE and/or Philips data?
+Are you experienced with parsing stimulus presentation log-files? Or do you have ideas to improve
+BIDScoin or its documentation? Have you come across bugs? In any case, you are more than welcome
+to provide feedback and to `contribute <https://github.com/Donders-Institute/bidscoin/blob/master/CONTRIBUTING.rst>`__
+to this project.

docs/bidsmap.rst

@@ -4,11 +4,11 @@ The bidsmap explained
 Structure and content
 ---------------------
 
-A central concept in BIDScoin is the so-called bidsmap. Generally speaking, a bidsmap is a collection of run-items that define how source data types (e.g. a T1w- or a T2w-scan) should be converted to `BIDS data types <https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#definitions>`__. As illustrated in the figure below (but see also the screenshot of the `edit window <screenshots.html>`__), run-items consist of a 'provenance' field and a 'properties', 'attributes', 'bids' and a 'meta' `dictionary <https://en.wikipedia.org/wiki/Associative_array>`__ (a set of key-value pairs):
+A central concept in BIDScoin is the so-called bidsmap. Generally speaking, a bidsmap is a collection of run-items that define how source data types (e.g. a T1w- or a T2w-scan) should be converted to `BIDS data types <https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#definitions>`__. As illustrated in the figure below (but see also the screenshot of the `edit window <./screenshots.html>`__), run-items consist of a 'provenance' field and a 'properties', 'attributes', 'bids' and a 'meta' `dictionary <https://en.wikipedia.org/wiki/Associative_array>`__ (a set of key-value pairs):
 
 1. **The provenance field** contains the pathname of a source data sample that is representative for the run-item. The provenance data is not strictly necessary but very useful for deeper inspection of the source data and for tracing back the conversion process, e.g. in case of encountering unexpected results
 2. **The properties dictionary** contains file system properties of the data sample, i.e. the file path, the file name, the file size on disk and the number of files in the containing folder. Depending on your data management, this information allows or can help to identify different datatypes in your source data repository
-3. **The attributes dictionary** contains attributes from the source data itself, such as the 'ProtocolName' from the DICOM header. The source attributes are a very rich source of information of which a minimal subset is normally sufficient to identify the different datatypes in your source data repository. The attributes are read from (the header of) the source file itself or, if present, from an accompanying sidecar file. This sidecar file transparently extends (or overrule) the available source attributes, as if that data would have been written to (the header of) the source data file itself. The name of the sidecar file should be the same as the name of the first associated source file and have a ``.json`` file extension. For instance, the ``001.dcm``, ``002.dcm``, ``003.dcm``, [..], DICOM source images can have a sidecar file in the same directory named ``001.json`` (e.g. containing metadata that is not available in the DICOM header or that must be overruled). It should be noted that BIDScoin `plugins <plugins.html>`__ will copy the extended attribute data over to the json sidecar files in your BIDS output folder, giving you additional control to generate your BIDS sidecar files (in addition to the meta dictionary described in point 5 below).
+3. **The attributes dictionary** contains attributes from the source data itself, such as the 'ProtocolName' from the DICOM header. The source attributes are a very rich source of information of which a minimal subset is normally sufficient to identify the different datatypes in your source data repository. The attributes are read from (the header of) the source file itself or, if present, from an accompanying sidecar file. This sidecar file transparently extends (or overrule) the available source attributes, as if that data would have been written to (the header of) the source data file itself. The name of the sidecar file should be the same as the name of the first associated source file and have a ``.json`` file extension. For instance, the ``001.dcm``, ``002.dcm``, ``003.dcm``, [..], DICOM source images can have a sidecar file in the same directory named ``001.json`` (e.g. containing metadata that is not available in the DICOM header or that must be overruled). It should be noted that BIDScoin `plugins <./plugins.html>`__ will copy the extended attribute data over to the json sidecar files in your BIDS output folder, giving you additional control to generate your BIDS sidecar files (in addition to the meta dictionary described in point 5 below).
 4. **The bids dictionary** contains the BIDS datatype and entities that determine the filename of the BIDS output data. The values in this dictionary are encouraged to be edited by the user
 5. **The meta dictionary** contains custom key-value pairs that are added to the json sidecar file by the BIDScoin plugins. Meta data may well vary from session to session, hence this dictionary often contains dynamic attribute values that are evaluated during bidscoiner runtime (see the `special features <#special-bidsmap-features>`__ below)
 

docs/installation.rst

@@ -20,7 +20,7 @@ To install BIDScoin on your system run one of the following commands in your com
    $ pip install bidscoin[deface,pet2bids]      # Use this when you want to deface anatomical MRI scans and convert PET data with the pet2bids plugin
    $ pip install bidscoin[all]                  # Use this to install all extra packages
 
-These install commands can be run independently and will give you the latest stable release of BIDScoin and its `plugins <options.html#dcm2niix2bids-plugin>`__. Alternatively, if you need to use the very latest (development / unstable) version of the software, you can also install BIDScoin directly from the github source code repository, e.g. like this:
+These install commands can be run independently and will give you the latest stable release of BIDScoin and its `plugins <./options.html#dcm2niix2bids-plugin>`__. Alternatively, if you need to use the very latest (development / unstable) version of the software, you can also install BIDScoin directly from the github source code repository, e.g. like this:
 
 .. code-block:: console
 
@@ -51,7 +51,7 @@ Run your pip install command as before with the additional ``--upgrade`` or ``--
 
 .. caution::
    - The bidsmaps are not guaranteed to be compatible between different BIDScoin versions
-   - After a successful BIDScoin installation or upgrade, it may be needed to (re)do any adjustments that were done on your `template bidsmap <bidsmap.html#building-your-own-template-bidsmap>`__
+   - After a successful BIDScoin installation or upgrade, it may be needed to (re)do any adjustments that were done on your `template bidsmap <./bidsmap.html#building-your-own-template-bidsmap>`__
 
 .. _Options: options.html
 .. _virtual: https://docs.python.org/3/tutorial/venv.html
@@ -80,7 +80,7 @@ You can run the 'bidscoin' utility to test the installation of your BIDScoin ins
    $ bidscoin -t                        # Test with the default template bidsmap
    $ bidscoin -t my_template_bidsmap    # Test with your custom template bidsmap
 
-See also the `Troubleshooting guide <troubleshooting.html#installation>`__ for more information on potential installation issues.
+See also the `Troubleshooting guide <./troubleshooting.html#installation>`__ for more information on potential installation issues.
 
 Using an Apptainer (Singularity) container
 ------------------------------------------