referencing all URLs with substitutions

README.md

@@ -1,3 +1,5 @@
 # Legume CHOICE sphinx documentation
 
 This documentation was built using sphinx. To view full details of the documentation, and for a full description of the whole legumeCHOICE tool, please see the [full documentation](https://legume-choice-docs.readthedocs.io/).
+
+The URLs and links are all referenced using substitutions. For more details on this, or to change the links to refer to your own legumeCHOICE implementation, please see the `conf.py` file.

conf.py

@@ -17,6 +17,7 @@
 import sphinx_markdown_tables
 from recommonmark.parser import CommonMarkParser
 from recommonmark.transform import AutoStructify
+import myst_parser
 # -- Project information -----------------------------------------------------
 
 project = 'LegumeCHOICE'
@@ -31,8 +32,9 @@
 # ones.
 extensions = [
     "sphinx_rtd_theme",
-    'recommonmark',
+    #'recommonmark',
     'sphinx_markdown_tables',
+    'myst_parser'
 ]
 
 
@@ -45,15 +47,43 @@ def setup(app):
     app.add_transform(AutoStructify)
 
 
-source_parsers = {
-    '.md': CommonMarkParser,
-}
+# source_parsers = {
+#     '.md': CommonMarkParser,
+# }
+
+# source_suffix = {
+#     '.rst': 'restructuredtext',
+#     '.md': 'markdown'
+# }
+
+
+myst_enable_extensions = [
+    "substitution"
+]
 
-source_suffix = {
-    '.rst': 'restructuredtext',
-    '.md': 'markdown'
+### All of the main substitutions to add to the sphinx documentation
+# To reference any of these, use either {{key}}, to reference in text.
+# Or use {{ '[here]({})'.format(key) }} to link in text
+# For multiple component links simply build on this
+# {{ '[NEW LINK]({}{})'.format(key1,key2) }}
+# See here for documentation on these types of substitution https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html
+myst_substitutions = {
+  "githubBase":"https://github.com/l-gorman/",  
+  "frontEndRepo": "legume-choice-client",
+  "apiRepo": "legume-choice-api",
+  "docsRepo": "legume-choice-docs",
+  "serverConfRepo": "legume-choice-conf",
+  "dataProcessingRepo": "legume-choice-data-processing",
+
+  "appURL": "https://l-gorman.github.io/legume-choice-client/",
+  "apiUrl": "https://l-gorman.com/",
+  "publicData": "LegumeCHOICE",
+  "adminData": "AdminLegumeCHOICE"
 }
 
+
+
+
 latex_elements = {
   'extraclassoptions': 'openany,oneside'
 }

source/administrators.md

@@ -1,5 +1,5 @@
 # Administrator Guidance
 
-Administrators of the legumeCHOICE tool have the ability to view and update the raw data collected by users of the tool. To access the raw data, administrators should visit [this page](https://l-gorman.com/AdminLegumeCHOICE/). They will be prompted to enter a username and password which are known only to administrators.
+Administrators of the legumeCHOICE tool have the ability to view and update the raw data collected by users of the tool. To access the raw data, administrators should visit {{ '[this page]({}{})'.format(apiUrl,adminData) }}. They will be prompted to enter a username and password which are known only to administrators.
 
 Administrators can download the raw data in JSON format. To view how to load and submit data, administrators should refer to the _managing data_ section of [Using the App](legume-choice-app.md)

source/api.md

@@ -1,3 +1,3 @@
 # API
 
-The API used for this project is a very simple express API. The API can be cloned [here](https://github.com/l-gorman/legume-choice-api). Clone the repository, change to the project directory using the command `cd legume-choice-api` and ensure dependencies are installed using the command `npm install`. The database models can be found in the `models` folder, and the routes in the `routes` folder. The api can be started using the command `node server.js` (it will run on port 5000 by default).
+The API used for this project is a very simple express API. The API can be cloned {{ '[here]({}{})'.format(githubBase,apiRepo) }}. Clone the repository, change to the project directory using the command `cd legume-choice-api` and ensure dependencies are installed using the command `npm install`. The database models can be found in the `models` folder, and the routes in the `routes` folder. The api can be started using the command `node server.js` (it will run on port 5000 by default).

source/contribute-to-the-guide.md

@@ -1,3 +1,3 @@
 # Documentation
 
-This documentation was created using sphinx and is hosted on readthedocs. The repository for this documentation can be found [here](https://github.com/l-gorman/legume-choice-docs). The markdown files which contain the content can all be found in the `source` directory. To add new sections to the documentation, add a new markdown (or RST) file to the source directory, and refer to the file in the toctree (found in the `index.rst` file) to ensure it is included in the table of contents.
+This documentation was created using sphinx and is hosted on readthedocs. The repository for this documentation can be found {{ '[here]({}{})'.format(githubBase,docsRepo) }}. The markdown files which contain the content can all be found in the `source` directory. To add new sections to the documentation, add a new markdown (or RST) file to the source directory, and refer to the file in the toctree (found in the `index.rst` file) to ensure it is included in the table of contents.

source/data-processing.md

@@ -1,5 +1,5 @@
 # Data Processing
 
-The data-processing is done using a series of python scripts. These can be accessed [here](https://github.com/l-gorman/legume-choice-data-processing). One script `daemon.py` listens for changes in the MongoDB database. When a change occurs, the script `FormatAllData.py` is run to reformat the data, and generate a series of CSVs. These CSVs are then made available for download through folders on the linux virtual machine (see [server description](nginx.md)).
+The data-processing is done using a series of python scripts. These can be accessed {{ '[here]({}{})'.format(githubBase,dataProcessingRepo) }}. One script `daemon.py` listens for changes in the MongoDB database. When a change occurs, the script `FormatAllData.py` is run to reformat the data, and generate a series of CSVs. These CSVs are then made available for download through folders on the linux virtual machine (see [server description](nginx.md)).
 
 To run this script locally, and produce modified outputs, ensure the requirements are installed (see `requirments.txt`), then run the command `python3 FormatAllData.py`. The python daemon is daemonized using systemd.

source/developer-overview.md

@@ -6,4 +6,4 @@ Each of the following sections, describes these components in more detail. In pa
 
 ## Developing App Locally
 
-If you are developing the application locally, the only components needed are the front-end, the express-api, and the database. Ensure you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [node](https://nodejs.org/en/download/) installed. Clone the repositories for the [API](https://github.com/l-gorman/legume-choice-api) and the [React App](https://github.com/l-gorman/legume-choice-client). To start the api, ensure you are in the directory `legume-choice-api` and run the command `npm install` followed by the command `node server.js` (by default this will run on port 5000). You can then run the front end by changing to the directory `legume-choice-client`. Run the command `npm install` followed by the commmand `npm start`. Note to make requests to your local MongoDB database, you must ensure that you are submitting to the correct URL. To check this, when in npm the directory `legume-choice-client`, check the file `src/components/submit-data-component/submit-data-component.js`. Navigate to the line where requests are made, and make sure the url is `http://localhost:5000/api/projects/submit-data/`. To explore the database, see the instructions in the [database](database.md) section.
+If you are developing the application locally, the only components needed are the front-end, the express-api, and the database. Ensure you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [node](https://nodejs.org/en/download/) installed. Clone the repositories for the {{ '[API]({}{})'.format(githubBase,apiRepo) }} and the {{ '[React App]({}{})'.format(githubBase,frontEndRepo) }}. To start the api, ensure you are in the directory `legume-choice-api` and run the command `npm install` followed by the command `node server.js` (by default this will run on port 5000). You can then run the front end by changing to the directory `legume-choice-client`. Run the command `npm install` followed by the commmand `npm start`. Note to make requests to your local MongoDB database, you must ensure that you are submitting to the correct URL. To check this, when in npm the directory `legume-choice-client`, check the file `src/components/submit-data-component/submit-data-component.js`. Navigate to the line where requests are made, and make sure the url is `http://localhost:5000/api/projects/submit-data/`. To explore the database, see the instructions in the [database](database.md) section.

source/front-end.md

@@ -1,8 +1,6 @@
 # Front-End
 
-The application is a Progressive Web App (PWA). This means that most modern browsers allow users to install the application locally. The source code for the application can be found [here](https://github.com/l-gorman/legume-choice-client). To contribute to this application, please ensure you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [node](https://nodejs.org/en/download/) installed. To clone the application enter:
-
-`git clone https://github.com/l-gorman/legume-choice-client`
+The application is a Progressive Web App (PWA). This means that most modern browsers allow users to install the application locally. The source code for the application can be found [here](https://github.com/l-gorman/legume-choice-client). To contribute to this application, please ensure you have [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [node](https://nodejs.org/en/download/) installed. To clone the application enter: `git clone URL`, replacing `URL` with _{{githubBase}}{{frontEndRepo}}_
 
 Change to the app directory (using `cd legume-choice-client`). You then need to install all of the dependencies using the command `npm install`. To start developing the application locally, run `npm start`, the application should then load in your browser and you can begin editing components. the code for each of the components can be found in the directory `./src/components`. This will contain a folder for each of the components. The names of the components should be self explanatory, and comments within each components should sufficiently explain
 

source/key-vm-commands.md

@@ -2,10 +2,10 @@
 
 This document contains key information to get started working with the legumeCHOICE VM. It includes some information about where important files are stored as well as a cheatsheet for running, stopping, and restarting processes.
 
-A repository has been created for two of the main server files, this can be found [here](https://github.com/l-gorman/legume-choice-conf).
+A repository has been created for two of the main server files, this can be found {{ '[here]({}{})'.format(githubBase,serverConfRepo) }}.
 
 To restart the NGINX server enter the command `systemctl restart nginx`
 
 To restart the python daemon enter the command `systemctl restart legume_choice_data_process.service`, followed by the command `systemctl daemon-reload`.
 
-To restart the API, enter the command `pm2 restart ~ubuntu/legumeCHOICE/api/server.js`.
+To restart the API, enter the command `pm2 restart ~USERNAME/legumeCHOICE/api/server.js`.

source/legume-choice-app.md

@@ -1,6 +1,6 @@
 # Using the App
 
-This section provides an overview of how to get started with the legumeCHOICE app. The app can be viewed and downloaded [here](https://l-gorman.github.io/legume-choice-client/). To download the application, visit the page. To the right of the URL (in the search bar) there should be a button to download in the app. If you are having trouble downloading the app, try updating your browser.
+This section provides an overview of how to get started with the legumeCHOICE app. The app can be viewed and downloaded {{ '[here]({})'.format(appURL) }}. To download the application, visit the page. To the right of the URL (in the search bar) there should be a button to download in the app. If you are having trouble downloading the app, try updating your browser.
 
 When using the app, you will be directed to the "information" page. We recommend reading the description of the tool, and downloading the original guide. To navigate between different parts of the application, open the menu using the button in the top-left corner. The pages are arranged in the order that the data should be collected (i.e. begin at the top and work your way down through each item).
 

source/public-data.md

@@ -1,6 +1,6 @@
 # Public Data
 
-This section describes how public data is presented. The legumeCHOICE public data can be found [here](https://l-gorman.com/LegumeCHOICE/).
+This section describes how public data is presented. The legumeCHOICE public data can be found {{ '[here]({}{})'.format(apiUrl,publicData) }}.
 Data can be broken down into two categories, **AggregatedProjects** and **IndividualProjects**.
 
 The **IndividualProjects** folder contains reformatted results for each individual project which has been collected. These projects can be identified by their project ID (see [using the app](legume-choice-app.md)). The **AggregatedProjects** folder includes results for all of the projects together, in single CSVs.