[ReadTheDocs] Structure and template fixes (#6667)

Fixes merge conflicts in the wiki (99 - Developers should not exists).
Fixes several errors including some which prevents the Loris ReadTheDocs to compile
(last compiled version is 4 months old now).

Demo: https://loris-dev.readthedocs.io/en/latest

Docs is now part of the breadcrumb. I can probably find a way to remove it if that's undesirable.
Symlinks are problematic (and as pointed here, not really useful) as we need (for now) to use relative links across all the documentation to avoid broken links.

    Resolves #6209
    Resolves #6329
    Resolves #6545
    Resolves #6622
    Resolves #6623
    Resolves #6737
    Resolves #6736

.readthedocs.yml

@@ -7,13 +7,13 @@ version: 2
 
 # Build documentation with MkDocs
 mkdocs:
-  configuration: mkdocs.yml
+  configuration: readthedocs/mkdocs.yml
   fail_on_warning: false
 
 python:
   version: 3.7
   install:
-      - requirements: docs/requirements.txt
+      - requirements: readthedocs/requirements.txt
 
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: []

CONTRIBUTING.md

@@ -67,7 +67,7 @@ issues and/or Redmine tickets (if applicable).
   directory. You can look at other modules for examples of how to
   write tests.
 * Before sending any pull request, make sure you run our static analysis tools 
-locally. More information can be found in the [testing guide](./docs/wiki/99%20-%20Developers/Automated%20Testing.md). 
+locally. More information can be found in the [testing guide](./docs/wiki/99_Developers/Automated_Testing.md). 
 * Try and make all changes backwards-compatible with existing installations.  
 * If you must change something in a non-backwards-compatible way - or if it 
 would affect the data or custom code of a study - document this in your pull 

docs/CodingStandards.md

@@ -5,7 +5,7 @@
 ### Style and Formatting
 We use a variety of static analysis tools to create a consistent style across
 the codebase. For more details about the tools used and what they do,
-please review the [Automated Testing Guide](./wiki/99%20-%20Developers/Automated%20Testing.md)
+please review the [Automated Testing Guide](./wiki/99_Developers/Automated_Testing.md)
 
 ### Separation of languages
 HTML, PHP, CSS, SQL, and JavaScript code should not be mixed. Instead, they

docs/wiki/01_STUDY_PARAMETERS_SETUP/01_Study_Variables/02_Projects.md

@@ -23,9 +23,8 @@ Projects can be added directly in SQL using the following command. The `recruitm
 INSERT INTO Project (Name, recruitmentTarget) VALUES('%PROJECT_NAME%', NULL);
 ```
 
-
 ### API
- _not yet available. See [API documentation](../../../API/) for latest additions_
+_not yet available. See [API documentation](../../99_Developers/LORIS-REST-API-0.0.3-dev.md) for latest additions_
 
 ## Interaction With LORIS
 **Projects** can have a direct effect on some LORIS modules where users will only be able to access data affiliated with their own projects.

docs/wiki/01_STUDY_PARAMETERS_SETUP/01_Study_Variables/03_Sites.md

@@ -33,8 +33,7 @@ INSERT INTO psc (Name, Alias, MRI_alias, Study_site) VALUES ('Montreal','MTL','M
 
 ### API
 
- _not yet available. See [API documentation](../../../API/) for latest
-additions_
+_not yet available. See [API documentation](../../99_Developers/LORIS-REST-API-0.0.3-dev.md) for latest additions_
 
 ## Interaction With LORIS
 

docs/wiki/01_STUDY_PARAMETERS_SETUP/01_Study_Variables/04_Subprojects.md

@@ -23,11 +23,9 @@ Subprojects can be added directly in SQL using the following command.
 INSERT INTO subproject (title) VALUES('SCI');
 ```
 
-
 ### API
- _not yet available. See [API documentation](../../../API/) for latest additions_
+_not yet available. See [API documentation](../../99_Developers/LORIS-REST-API-0.0.3-dev.md) for latest additions_
 
-
 ## Interaction With LORIS
 
 ### Projects

docs/wiki/01_STUDY_PARAMETERS_SETUP/01_Study_Variables/05_Timepoints.md

@@ -29,7 +29,7 @@ INSERT INTO visit (VisitName) VALUES ('V1');
 ```
 
 ### API
- _not yet available. See [API documentation](../../../API/) for latest additions_
+_not yet available. See [API documentation](../../99_Developers/LORIS-REST-API-0.0.3-dev.md) for latest additions_
 
 ## Interaction With LORIS
 

docs/wiki/99_Developers/Automated_Testing.md

@@ -85,14 +85,13 @@ Further information can be found at [the eslint website](https://eslint.org/docs
 
 **Dynamic testing** includes _unit tests_ and _integration tests_. A unit test is a small chunk of code that executes a function and make sure it does what it's supposed to using fake data. An integration test simulates a person using a web browser and interacting with UI elements, making sure that taking an action on a webpage causes a result that makes sense.
 
-We use Docker to help us simulate a server running LORIS. The installation and usage of Docker testing in LORIS is covered in our [testing README file in the `test/` directory](https://github.com/aces/Loris/blob/main/test/README.md).
+We use Docker to help us simulate a server running LORIS. The installation and usage of Docker testing in LORIS is covered in our [testing README file in the `test/` directory](../../../test/README.md).
 
 ### Unit Tests
 
 LORIS uses the [PHPUnit library](https://phpunit.de/) for unit tests.
 
-
-Unit testing is covered in depth in our [Unit Test Guide](/test/UnitTestGuide.md).
+Unit testing is covered in depth in our [Unit Test Guide](UnitTestGuide.md).
 
 Unit test files can be found in the folder `test/unittests/`.
 

docs/wiki/99_Developers/Help_Style_Guide.md

@@ -2,7 +2,7 @@
 
 Help text exists as an on-screen guide for users, to add context and provide instructions to using all of the features in LORIS. It is always accessed by clicking the question mark in the top right menu bar in LORIS, as seen below:
 
-![Help Text](/docs/images/helptext.png)
+![Help Text](./images/helptext.png)
 
 ## How to Store and Name Files
 

docs/wiki/99_Developers/LORIS-REST-API-0.0.2.md

@@ -0,0 +1 @@
+../../../modules/api/docs/LorisRESTAPI.md

docs/wiki/99_Developers/LORIS-REST-API-0.0.3-dev.md

@@ -0,0 +1 @@
+../../../modules/api/docs/LorisRESTAPI_v0.0.3.md

docs/wiki/99 - Developers/UnitTestGuide.md → docs/wiki/99_Developers/UnitTestGuide.md

@@ -1,4 +1,4 @@
-# **Unit Testing 101: How to Write Tests for LORIS**
+# Unit Testing 101: How to Write Tests for LORIS
 
 This guide is for [LORIS](http://loris.ca/) developers or anyone working with LORIS who wants to contribute unit tests to the [LORIS codebase](https://github.com/aces/Loris) and learn best practices for setting up and writing unit tests. 
 

modules/api/test/TestPlan.md

@@ -33,7 +33,7 @@ See specification for the expected response format.
 
 
 #### Candidate creation - POST /candidates
-Candidate creation is done by sending a POST request to /candidates with the required data. Note the usage of the Authorization header. For a candidate to be created, the candidate's information must also be included. The following command contains the minimal information necessary for the request to create a new candidate (see [docs](../../../docs/API/LorisRESTAPI_v0.0.3.md#30-candidate-api) for format instructions):
+Candidate creation is done by sending a POST request to /candidates with the required data. Note the usage of the Authorization header. For a candidate to be created, the candidate's information must also be included. The following command contains the minimal information necessary for the request to create a new candidate (see [docs](../../../docs/wiki/99_Developers/LORIS-REST-API-0.0.3-dev.md#30-candidate-api) for format instructions):
 
 ```bash
 ~$ curl -H "Authorization: Bearer $token" https://<your-hostname>/api/v0.0.3/candidates -d '{"Candidate":{"Project":"Rye","Site":"Montreal","DoB":"2019-01-31", "Sex":"Female"}}' 

modules/genomic_browser/README.md

@@ -32,4 +32,4 @@ uploading functionality to work.
 
 - For the methylation tab to work, the `genomic_cpg_annotation` table should be filled with data from the Illumina HumanMethylation450k probe annotations file. This file can be found at ftp://webdata2:webdata2@ussd-ftp.illumina.com/downloads/ProductFiles/HumanMethylation450/HumanMethylation450_15017482_v1-2.csv. Use the script `modules/genomic_browser/tools/HumanMethylation450k_annotations_to_sql.py` to transfer the csv file from Illumina's FTP to a mysql transaction file. (The process of loading the SQL file can take 5 to 10 minutes)
 - The `GenomicDataPath` configuration specifies where files are uploaded.
-- To enable uploads, please consult instructions for [Handling Large File Uploads](../../docs/wiki/00 - SERVER INSTALL AND CONFIGURATION/02 - Website Configuration/Handling Large File Uploads.md).
+- To enable uploads, please consult instructions for [Handling Large File Uploads](../../docs/wiki/00_SERVER_INSTALL_AND_CONFIGURATION/02_Website_Configuration/Handling_Large_File_Uploads.md).

modules/imaging_uploader/README.md

@@ -78,7 +78,7 @@ for more information.
 ### Install Configurations
 
 To enable the Imaging Uploader to handle large files, please follow the
-instructons for [Handling Large File Uploads](../../docs/wiki/00 - SERVER INSTALL AND CONFIGURATION/02 - Website Configuration/Handling Large File Uploads.md).
+instructons for [Handling Large File Uploads](../../docs/wiki/00_SERVER_INSTALL_AND_CONFIGURATION/02_Website_Configuration/Handling_Large_File_Uploads.md).
 
 #### <a name="database_config_link"></a> Database Configurations
 

readthedocs/mkdocs.yml

@@ -0,0 +1,54 @@
+site_name: LORIS
+repo_url: https://github.com/aces/Loris
+# Solve the broken 404 page issue
+site_url: https://acesloris.readthedocs.io/en/latest/
+
+nav:
+    - Home: 'README.md'
+    - Wiki: 'docs/wiki/index.md'
+    - Server Install and Configuration:
+        - 'Prerequisities and Assumptions': 'docs/wiki/00_SERVER_INSTALL_AND_CONFIGURATION/00_Prerequisites_And_Assumptions/README.md'
+        - 'Database Configuration': 'docs/wiki/00_SERVER_INSTALL_AND_CONFIGURATION/00_Prerequisites_And_Assumptions/Database_Configuration.md'
+        - Installation:
+            - 'Ubuntu Install': 'docs/wiki/00_SERVER_INSTALL_AND_CONFIGURATION/01_LORIS_Install/Ubuntu/README.md'
+            - 'CentOS Install': 'docs/wiki/00_SERVER_INSTALL_AND_CONFIGURATION/01_LORIS_Install/CentOS/README.md'
+        - Website Configuration:
+            - 'Website Configuration': 'docs/wiki/00_SERVER_INSTALL_AND_CONFIGURATION/02_Website_Configuration/README.md'
+            - 'Handling Large File Uploads': 'docs/wiki/00_SERVER_INSTALL_AND_CONFIGURATION/02_Website_Configuration/Handling_Large_File_Uploads.md'
+            - 'Enabling reCAPTCHA': 'docs/wiki/00_SERVER_INSTALL_AND_CONFIGURATION/02_Website_Configuration/reCAPTCHA.md'
+    - Study Parameters Setup:
+        - Study Variables:
+            - Introduction: 'docs/wiki/01_STUDY_PARAMETERS_SETUP/01_Study_Variables/00_Introduction_to_Study_Variables.md'
+            - Projects: 'docs/wiki/01_STUDY_PARAMETERS_SETUP/01_Study_Variables/02_Projects.md'
+            - Sites: 'docs/wiki/01_STUDY_PARAMETERS_SETUP/01_Study_Variables/03_Sites.md'
+            - Subprojects: 'docs/wiki/01_STUDY_PARAMETERS_SETUP/01_Study_Variables/04_Subprojects.md'
+            - Timepoints: 'docs/wiki/01_STUDY_PARAMETERS_SETUP/01_Study_Variables/05_Timepoints.md'
+        - Clinical Instruments: 'docs/wiki/01_STUDY_PARAMETERS_SETUP/02_Clinical_Instruments/README.md'
+        - Modules: 'docs/wiki/01_STUDY_PARAMETERS_SETUP/03_Loris_Modules/README.md'
+    - Getting Started: 'docs/wiki/02_GETTING_STARTED/README.md'
+    - Help and Troubleshooting: 'docs/wiki/03_HELP_AND_TROUBLESHOOTING/README.md'
+    - REST API:
+        - 'Stable' : 'docs/wiki/99_Developers/LORIS-REST-API-0.0.2.md'
+        - 'Dev' : 'docs/wiki/99_Developers/LORIS-REST-API-0.0.3-dev.md'
+    - Developers:
+        - Overview: 'docs/wiki/99_Developers/README.md'
+        - 'Coding Standards': 'docs/CodingStandards.md'
+        - 'SQL Dictionary': 'docs/wiki/99_Developers/SQL_Dictionary.md'
+        - 'Automated Testing': 'docs/wiki/99_Developers/Automated_Testing.md'
+        - 'Style Guide (for help text)': 'docs/wiki/99_Developers/Help_Style_Guide.md'
+        - 'Creating a Module': 'docs/wiki/99_Developers/Creating_Module.md'
+        - 'ReactJS Guidelines': 'docs/wiki/99_Developers/ReactJS_Guidelines.md'
+        - 'Code Review Guide': 'docs/wiki/99_Developers/Code_Review_Guide.md'
+
+use_directory_urls: False
+
+theme:
+    name: readthedocs
+    custom_dir: 'themes/loris_theme/'
+    navigation_depth: 4
+
+plugins:
+    - search
+    - root:
+        ignore_folders: ['node_modules', 'vendor', 'deprecated_wiki', '_DELETED', '_ARCHIVE']
+        ignore_hidden: True

readthedocs/plugins/mkdocs-root-plugin/mkdocs_root_plugin/plugin.py

@@ -0,0 +1,68 @@
+from mkdocs.plugins import BasePlugin
+from mkdocs.config import config_options
+
+import os
+import shutil
+import sys
+
+class RootPlugin(BasePlugin):
+    config_scheme = (
+        ('ignore_folders', config_options.Type(list, default=[])),
+        ('ignore_hidden', config_options.Type(bool, default=True))
+    )
+
+    def __init__(self):
+        self.docs_dir = "docs_"
+
+    def on_pre_build(self, config):
+        self.ignore_folders = self.config['ignore_folders']
+        self.ignore_folders += [config['docs_dir'],
+                                config['site_dir'],
+                                self.docs_dir]
+        self.ignore_hidden = self.config['ignore_hidden']
+        # Update the docs_dir with our temporary one!
+        self.orig_docs_dir = config['docs_dir']
+        config['docs_dir'] = self.docs_dir
+        # Add all md files from directory, keeping folder structure
+        self.paths = self.gen_from_dir()
+
+    def on_serve(self, server, config, **kwargs):
+        builder = list(server.watcher._tasks.values())[0]['func']
+
+        # still watch the original docs/ directory
+        if os.path.exists(self.orig_docs_dir):
+            server.watch(self.orig_docs_dir, builder)
+
+        # watch all the doc files
+        for orig, _ in self.paths:
+            server.watch(orig, builder)
+
+        return server
+
+    def on_post_build(self, config):
+        shutil.rmtree(self.docs_dir)
+
+    def valid_dir(self, dir):
+        if self.ignore_hidden and dir[0] == ".":
+            return False
+        if dir in self.ignore_folders:
+            return False
+        return True
+
+    def gen_from_dir(self):
+        paths = []
+        for root, dirs, files in os.walk("."):
+            for f in files:
+                if any (s in f for s in ('.md', '.svg', '.png', '.jpg')):
+                    doc_root = "./" + self.docs_dir + root[1:]
+                    orig = "{}/{}".format(root, f)
+                    new = "{}/{}".format(doc_root, f)
+                    try:
+                        os.makedirs(doc_root, exist_ok=True)
+                        shutil.copy(orig, new)
+                        paths.append((orig, new))
+                    except Exception as e:
+                        print("ERROR: {}.. skipping {}".format(e, orig))
+
+            dirs[:] = [d for d in dirs if self.valid_dir(d)]
+        return paths

readthedocs/plugins/mkdocs-root-plugin/setup.py

@@ -0,0 +1,17 @@
+import setuptools
+
+setuptools.setup(
+    name='mkdocs-root-plugin',
+    version='0.0.1',
+    python_requires='>=3',
+    install_requires=[
+        'mkdocs>=1.0.6',
+        'click>=7.1'
+    ],
+    packages=setuptools.find_packages(),
+    entry_points={
+        'mkdocs.plugins': [
+            'root = mkdocs_root_plugin.plugin:RootPlugin'
+        ]
+    }
+)

readthedocs/requirements.txt

@@ -0,0 +1,2 @@
+mkdocs==1.1
+./readthedocs/plugins/mkdocs-root-plugin

readthedocs/themes/loris_theme/breadcrumbs.html

@@ -0,0 +1,43 @@
+<div role="navigation" aria-label="breadcrumbs navigation">
+  <ul class="wy-breadcrumbs">
+    <li><a href="{{ nav.homepage.url|url }}">Docs</a> &raquo;</li>
+    {% if page %}
+      {% for doc in page.ancestors|reverse %}
+        {% if doc.link %}
+          <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</li>
+        {% else %}
+          <li>{{ doc.title }} &raquo;</li>
+        {% endif %}
+      {% endfor %}
+    {% endif %}
+
+    {% if page %}<li>{{ page.title }}</li>{% endif %}
+
+    <li class="wy-breadcrumbs-aside">
+      {%- block repo %}
+      {% if page and page.edit_url %}
+        <a href="{{ page.edit_url }}"
+        {%- if config.repo_name|lower == 'github' %}
+          class="icon icon-github"
+        {%- elif config.repo_name|lower == 'bitbucket' %}
+          class="icon icon-bitbucket"
+        {%- elif config.repo_name|lower == 'gitlab' %}
+          class="icon icon-gitlab"
+        {% endif %}> Edit on {{ config.repo_name }}</a>
+      {% endif %}
+      {%- endblock %}
+    </li>
+  </ul>
+  {% if config.theme.prev_next_buttons_location|lower in ['top', 'both']
+        and page and (page.next_page or page.previous_page) %}
+    <div class="rst-breadcrumbs-buttons" role="navigation" aria-label="breadcrumb navigation">
+      {%- if page.next_page %}
+        <a href="{{ page.next_page.url|url }}" class="btn btn-neutral float-right" title="{{ page.next_page.title }}">Next <span class="icon icon-circle-arrow-right"></span></a>
+      {%- endif %}
+      {%- if page.previous_page %}
+        <a href="{{ page.previous_page.url|url }}" class="btn btn-neutral" title="{{ page.previous_page.title }}"><span class="icon icon-circle-arrow-left"></span> Previous</a>
+      {%- endif %}
+    </div>
+  {% endif %}
+  <hr/>
+</div>