[ENH] Own DIR for getting started

Fixes #99

docs/cli.md

@@ -177,7 +177,7 @@ You could run the CLI as follows:
 Neurobagel is under active, early development and future releases of the CLI may introduce breaking changes to the data model for subject-level information in a `.jsonld` graph file. Breaking changes will be highlighted in the release notes!
 
 _If you have already created `.jsonld` files for your Neurobagel graph database using the CLI_, 
-they can be quickly re-generated under the new data model by following the instructions [here](maintaining.md#following-a-change-in-the-neurobagel-data-model) so that they will not conflict with dataset `.jsonld` files generated using the latest CLI version.
+they can be quickly re-generated under the new data model by following the instructions [here](guide/maintaining.md#following-a-change-in-the-neurobagel-data-model) so that they will not conflict with dataset `.jsonld` files generated using the latest CLI version.
 
 
 ## Development environment

docs/config.md → docs/guide/config.md

@@ -15,14 +15,14 @@ and coordinates them to work together:
 
 (In parentheses are the names of services within the Docker Compose stack)
 
-- **[Neurobagel node API/n-API](api.md)** (`api`): The API that communicates with a single graph store and determines 
+- **[Neurobagel node API/n-API](../api.md)** (`api`): The API that communicates with a single graph store and determines 
     how detailed the response to a query should be from that graph.
 - **Graph store** (`graph`): A third-party RDF store that stores Neurobagel-harmonized data to be queried. At the moment our recipe uses the free tier
     of [GraphDB](https://db-engines.com/en/system/GraphDB) for this.
 - **Neurobagel federation/f-API** (`federation`): A special API that can federate over one or more
     Neurobagel nodes to provide a single point of access to multiple distributed databases.
     By default it will federate over all public nodes and any local nodes you specify. 
-- **[Neurobagel query tool](query_tool.md)** (`query_tool`): A web app that provides a graphical interface for users to query a 
+- **[Neurobagel query tool](../query_tool.md)** (`query_tool`): A web app that provides a graphical interface for users to query a 
     federation API and view the results from one or more nodes. Because the query tool is a static app and is run locally
     in the user's browser, this service simply hosts the app.
 
@@ -309,7 +309,7 @@ you can use the
     hierarchical relationships between concepts themselves can also be represented.
     Including these relationships in a graph is important to be able to answer questions such as how many different diagnoses are represented in a graph database, to query for higher-order concepts for a given variable, and more.
 
-The participant variables modeled by Neurobagel are named using Neurobagel's own vocabulary (for more information, see this page on [controlled terms](./term_naming_standards.md)).
+The participant variables modeled by Neurobagel are named using Neurobagel's own vocabulary (for more information, see this page on [controlled terms](../term_naming_standards.md)).
 This vocabulary, which defines internal relationships between vocabulary terms, 
 is serialized in the file [`nb_vocab.ttl`](https://github.com/neurobagel/recipes/blob/main/vocab/nb_vocab.ttl) available from the `neurobagel/recipes` repository.
 If you have cloned this repository, you will already have downloaded the vocabulary file.

docs/getting_started.md → docs/guide/getting_started.md

@@ -5,7 +5,7 @@ and a local federation API
 (everything in blue in the picture below)
 that lets you search across the data in your node and in public Neurobagel nodes.
 
-![Neurobagel node](imgs/neurobagel_local_node.jpg)
+![Neurobagel node](../imgs/neurobagel_local_node.jpg)
 
 To prepare your Neurobagel node for production use (i.e., for local or other users),
 and to configure your deployment according to your specific needs,
@@ -98,7 +98,7 @@ cp local_nb_nodes.template.json local_nb_nodes.json
     with the URL address where the Neurobagel federation API will be accessed:
 
     - If you are deploying Neurobagel for yourself or deploying and trying the services **on your local machine only**, 
-   you can use `NB_API_QUERY_URL=http://localhost:8080`, where `8080` is the [default host port for the federation API](./config.md#environment-variables).
+   you can use `NB_API_QUERY_URL=http://localhost:8080`, where `8080` is the [default host port for the federation API](config.md#environment-variables).
     - If you are deploying Neurobagel **on a server for other users**, 
    you must use the IP (and port) or URL intended for your users to access the federation API on the server with.
 
@@ -151,9 +151,9 @@ our [service profile documentation](config.md#available-profiles) for details.
 :tada: You are now the proud owner of a running Neurobagel node. Here are some things you can do now:
 
 - Try the Neurobagel node you just deployed by accessing:
-    - your own query tool at  [http://localhost:3000](http://localhost:3000), and reading the [query tool usage](./query_tool.md#usage) guide
-    - the interactive docs for your node API at [http://localhost:8000/docs](http://localhost:8000/docs), and reading the [API usage](./api.md) guide
-- [Prepare your own dataset](./data_prep.md) for annotation with Neurobagel
+    - your own query tool at  [http://localhost:3000](http://localhost:3000), and reading the [query tool usage](../query_tool.md#usage) guide
+    - the interactive docs for your node API at [http://localhost:8000/docs](http://localhost:8000/docs), and reading the [API usage](../api.md) guide
+- [Prepare your own dataset](../data_prep.md) for annotation with Neurobagel
 - [Add your own data to your Neurobagel graph](maintaining.md#updating-the-data-in-your-graph) to search
 - Learn about the different [configuration options](config.md) for your Neurobagel node
-- Hopefully all went well, but if you are experiencing issues, see how to [get help](./getting_help.md)
+- Hopefully all went well, but if you are experiencing issues, see how to [get help](../getting_help.md)

docs/maintaining.md → docs/guide/maintaining.md

@@ -118,35 +118,35 @@ For any of the below types of changes, you will need to regenerate a graph-ready
 
 If new variables have been added to the dataset such that there are new columns in the phenotypic TSV you previously annotated using Neurobagel's annotation tool, you will need to:  
 
-1. **Generate an updated data dictionary** by annotating the new variables in your TSV following the [annotation workflow](annotation_tool.md)
+1. **Generate an updated data dictionary** by annotating the new variables in your TSV following the [annotation workflow](../annotation_tool.md)
 
-2. **Generate a new graph-ready data file** for the dataset by [re-running the CLI](cli.md) on your updated TSV and data dictionary
+2. **Generate a new graph-ready data file** for the dataset by [re-running the CLI](../cli.md) on your updated TSV and data dictionary
 
 #### If only the imaging data have changed
 
 If the BIDS data for a dataset have changed without changes in the corresponding phenotypic TSV (e.g., if new modalities or scans have been acquired for a subject), you have two options:
 
-- If you still have access to the dataset's phenotypic JSONLD generated from the `pheno` command of the `bagel-cli` (step 1), you may choose to [rerun only the `bids` CLI command](cli.md) on the updated BIDS directory.
+- If you still have access to the dataset's phenotypic JSONLD generated from the `pheno` command of the `bagel-cli` (step 1), you may choose to [rerun only the `bids` CLI command](../cli.md) on the updated BIDS directory.
 This will generate a new graph-ready data file with updated imaging metadata of subjects.
 
 OR
 
-- [Rerun the CLI entirely (`pheno` and `bids` steps)](cli.md) to generate a new graph-ready data file for the dataset.
+- [Rerun the CLI entirely (`pheno` and `bids` steps)](../cli.md) to generate a new graph-ready data file for the dataset.
 
 _When in doubt, rerun both CLI commands._
 
 #### If only the subjects have changed
 
 If subjects have been added to or removed from the dataset but the phenotypic TSV is otherwise unchanged (i.e., only new or removed rows, without changes to the available variables), you will need to:
 
-- **Generate a new graph-ready data file** for the dataset by [re-running the CLI](cli.md) (`pheno` and `bids` steps) on your updated TSV and existing data dictionary
+- **Generate a new graph-ready data file** for the dataset by [re-running the CLI](../cli.md) (`pheno` and `bids` steps) on your updated TSV and existing data dictionary
 
 ### Following a change in the _Neurobagel data model_
 
 As Neurobagel continues developing the data model, new tool releases may introduce breaking changes to the data model for subject-level information in a `.jsonld` graph data file.
 Breaking changes will be highlighted in the release notes.
 
-_If you have already created `.jsonld` files for a Neurobagel graph database_ but want to update your graph data to the latest Neurobagel data model following such a change, you can easily do so by [rerunning the CLI](cli.md) on the existing data dictionaries and phenotypic TSVs for the dataset(s) in the graph.
+_If you have already created `.jsonld` files for a Neurobagel graph database_ but want to update your graph data to the latest Neurobagel data model following such a change, you can easily do so by [rerunning the CLI](../cli.md) on the existing data dictionaries and phenotypic TSVs for the dataset(s) in the graph.
 This will ensure that if you use the latest version of the Neurobagel CLI to process new datasets (i.e., generate new `.jsonld` files) for your database, the resulting data will not have conflicts with existing data in the graph.
 
 Note that if upgrading to a newer version of the data model, **you should regenerate the `.jsonld` files for _all_ datasets in your existing graph**.

docs/overview.md

@@ -22,5 +22,5 @@ You can also find official Docker images for our containerized tools on the [Neu
 ## What to do next
 
 - [Learn how to run a cohort query](./query_tool.md) on publicly accessible Neurobagel nodes
-- [Deploy your own Neurobagel node](./getting_started.md) using our official Docker Compose recipe
+- [Deploy your own Neurobagel node](guide/getting_started.md) using our official Docker Compose recipe
 - [Prepare your own dataset](./data_prep.md) for annotation and harmonization with Neurobagel

docs/public_nodes.md

@@ -32,4 +32,4 @@ Downloading of imaging data is performed via [datalad](https://rpq-qpn.ca/en/hom
 Nodes that are not purposefully made public are not accessible 
 outside of the institute or network where they are deployed.
 If you are interested in deploying a Neurobagel node for your institution,
-please refer to our [deployment documentation](./getting_started.md) for more information.
+please refer to our [deployment documentation](guide/getting_started.md) for more information.

docs/query_tool.md

@@ -65,7 +65,7 @@ Example:
 
 If the values for all columns except for `DatasetID` and `SessionPath` in the participant-level results tsv are set to `protected`, this indicates the graph being queried has been configured (via its corresponding Neurobagel node API) to return only aggregate information about matches (due to data privacy reasons). 
 This configuration can be modified by setting the `NB_RETURN_AGG` environment variable to `false` (the value is by default `true`). 
-See related section of the documentation [here](config.md#environment-variables).
+See related section of the documentation [here](guide/config.md#environment-variables).
 
 Example:
 

mkdocs.yml

@@ -30,9 +30,9 @@ nav:
         - How to use the query tool: "query_tool.md"
         - Querying the API directly: "api.md"
     - Setting up your own Neurobagel node:
-        - Getting started: "getting_started.md"
-        - Configuring a node: "config.md"
-        - Maintaining a node: "maintaining.md"
+        - Getting started: "guide/getting_started.md"
+        - Configuring a node: "guide/config.md"
+        - Maintaining a node: "guide/maintaining.md"
     - Annotating your data:
         - Preparing data for annotation: "data_prep.md"
         - Annotation tool guide: "annotation_tool.md"