More tidying up.

JoeZiminski · JoeZiminski · commit 7bd8e28613d9 · 2025-03-22T19:56:25.000Z
diff --git a/docs/source/_static/screenshots/choose-a-terminal-bad-dark.png b/docs/source/_static/screenshots/choose-a-terminal-bad-dark.png
diff --git a/docs/source/_static/screenshots/choose-a-terminal-bad-light.png b/docs/source/_static/screenshots/choose-a-terminal-bad-light.png
diff --git a/docs/source/_static/screenshots/choose-a-terminal-good-dark.png b/docs/source/_static/screenshots/choose-a-terminal-good-dark.png
diff --git a/docs/source/_static/screenshots/choose-a-terminal-good-light.png b/docs/source/_static/screenshots/choose-a-terminal-good-light.png
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -59,6 +59,7 @@ A lack of project standardization in systems neuroscience
 [hinders data sharing and collaboration](https://neuroinformatics.dev/blog/neuroblueprint.html),
 creating barriers to reproducibility and scientific progress
 
+
 ``datashuttle`` helps creates, validate and transfer projects standardised to the
 [NeuroBlueprint](https://neuroblueprint.neuroinformatics.dev) specification:
 
@@ -74,10 +75,9 @@ creating barriers to reproducibility and scientific progress
 ```
 
 Dive right into ``datashuttle`` with our
-[Getting Started Tutorial](tutorial-getting-started)
-or targeted [How-To Guides](how-tos).  \
+[Getting Started Tutorial](getting-started-walkthrough)
+or targeted [User Guides](pages/user_guides/index).  \
 It can be used through a graphical interface or Python API.
-[create-folders.md](pages%2Fuser_guides%2Fcreate-folders.md)
 
 Don't hesitate to get in contact through our
 [GitHub Issues](https://github.com/neuroinformatics-unit/datashuttle/issues)
diff --git a/docs/source/pages/get_started/choose-a-terminal.md b/docs/source/pages/get_started/choose-a-terminal.md
@@ -1,6 +1,6 @@
-(how-to-choose-a-terminal)=
+(choose-a-terminal_)=
 
-# How to Choose a Terminal
+# Choose a Terminal
 
 ``datashuttle``'s graphical interface can run in almost any terminal—but
 native Windows and macOS terminals may display with rendering errors.
@@ -13,12 +13,12 @@ If you are using Linux, the native terminal will work without issue.
 
 :::{tab-item} Good Rendering
 
-```{image} /_static/screenshots/how-to-choose-a-terminal-good-dark.png
+```{image} /_static/screenshots/choose-a-terminal-good-dark.png
    :align: center
    :class: only-dark
    :width: 900px
 ```
-```{image} /_static/screenshots/how-to-choose-a-terminal-good-light.png
+```{image} /_static/screenshots/choose-a-terminal-good-light.png
    :align: center
    :class: only-light
    :width: 900px
@@ -30,12 +30,12 @@ If you are using Linux, the native terminal will work without issue.
 
 :::{tab-item} Bad Rendering
 
-```{image} /_static/screenshots/how-to-choose-a-terminal-bad-dark.png
+```{image} /_static/screenshots/choose-a-terminal-bad-dark.png
    :align: center
    :class: only-dark
    :width: 900px
 ```
-```{image} /_static/screenshots/how-to-choose-a-terminal-bad-light.png
+```{image} /_static/screenshots/choose-a-terminal-bad-light.png
    :align: center
    :class: only-light
    :width: 900px
@@ -80,6 +80,6 @@ with rendering errors.
 ## Getting started with the Graphical Interface
 
 Once you've chosen a terminal, get started with
-``datashuttle`` with our [Getting Started Tutorial](tutorial-getting-started).
+``datashuttle`` with our [Getting Started Tutorial](getting-started-walkthrough).
 
 To quit ``datashuttle`` in the terminal, press `CTRL+C`.
diff --git a/docs/source/pages/get_started/getting-started.md b/docs/source/pages/get_started/getting-started.md
@@ -1,4 +1,4 @@
-(tutorial-getting-started)=
+(getting-started-walkthrough)=
 
 # Getting Started
 
@@ -88,7 +88,7 @@ We need to set the:
 
 ``datashuttle`` supports connecting to the central storage machine
 either as a mounted drive or through SHH. \
-See [How to Make a New Project](make-a-full-project_target)
+See [Set up configs for transfer(set-up-configs-for-transfer_)
 for detailed instructions for
 connecting a mounted drive or by using SSH.
 
@@ -584,7 +584,7 @@ from your **local path**.
 We will next download data from the **central path** to our now-empty local project.
 
 In practice when setting up ``datashuttle`` on a new machine, you would
-again [make a new project](make-a-full-project_target).
+again [make a new project](set-up-configs-for-transfer_).
 ```
 
 We will look at a small subset of possible
diff --git a/docs/source/pages/get_started/index.md b/docs/source/pages/get_started/index.md
@@ -31,12 +31,12 @@ formatting issues
 :::
 
 
-:::{grid-item-card} {fas}`desktop;sd-text-primary` Manage a project
-:link: make-a-local-project
+:::{grid-item-card} {fas}`desktop;sd-text-primary` Set up a project
+:link: set-up-a-local-project
 :link-type: doc
 :class-img-top: tutorial-link-image
 
-Create, validate and transfer project folders
+Start a new project or manage an existing project
 :::
 
 ::::
@@ -66,7 +66,7 @@ install
 choose-a-terminal
 
 quick-validate-project
-make-a-local-project
+set-up-a-local-project
 
 getting-started
 ```
diff --git a/docs/source/pages/get_started/install.md b/docs/source/pages/get_started/install.md
@@ -1,5 +1,5 @@
 (how-to-install)=
-# How to Install
+# Install
 
 ``datashuttle`` requires
 [Python](https://www.python.org/)
@@ -97,5 +97,5 @@ datashuttle launch
 ```
 
 Before using the graphical interface, you may want to
-[choose the best terminal](how-to-choose-a-terminal)
+[choose the best terminal](choose-a-terminal_)
 for your operating system.
diff --git a/docs/source/pages/get_started/quick-validate-project.md b/docs/source/pages/get_started/quick-validate-project.md
@@ -1,6 +1,6 @@
 (quick-validate-projects)=
 
-# How to Quickly Validate an Existing Project
+# Quickly Validate an Existing Project
 
 Datashuttle provides the functionality to validate an existing
 [NeuroBlueprint](https://neuroblueprint.neuroinformatics.dev/latest/index.html)-formatted project.
diff --git a/docs/source/pages/get_started/set-up-a-local-project.md b/docs/source/pages/get_started/set-up-a-local-project.md
@@ -1,9 +1,15 @@
-# How to Make a Local Project
+(set-up-a-local-project)=
+# Set up a Local Project
+
+``datashuttle`` can be used to create, validate and transfer
+[NeuroBlueprint](https://neuroblueprint.neuroinformatics.dev/latest/index.html) projects. In this guide, we will
+set up a local-only project that can manage creation
+and validation of project folders. This requires
+setting up minimal configurations to get started.
+
+To see how a datashuttle project can be set up for transfer,
+see the [transfer](how-to-transfer-data) user guide.
 
-``datashuttle`` can be used to create and validate
-[NeuroBlueprint](https://neuroblueprint.neuroinformatics.dev/latest/index.html) projects,
-as well as transfer data. If you want to quickly create or validate a project's folders,
-but not transfer data, you can make a local-only project and immediately get started.
 
 ::::{tab-set}
 
@@ -28,6 +34,25 @@ are now disabled).
 ```
 <br>
 
+
+You will now be able to go to the project manager screen:
+
+```{image} /_static/screenshots/how-to-create-folders-example-dark.png
+   :align: center
+   :class: only-dark
+   :width: 900px
+```
+```{image} /_static/screenshots/how-to-create-folders-example-light.png
+   :align: center
+   :class: only-light
+   :width: 900px
+```
+<br>
+
+
+See the [create folders](how-to-create-folders) and [validate folders](tutorial-validation)
+for details on how to create and validate your project.
+
 :::
 
 :::{tab-item} Python API
@@ -62,7 +87,7 @@ have to set the `local_path` again).
 
 If you wish to change the project settings at a later time, use ``project.update_config_file()``.
 
-For example, it is possible to immediately validate the project:
+For example, it is possible to immediately validate the project (if it already exists):
 
 ```python
 project.validate_project("rawdata", error_or_warn="warn")
@@ -82,14 +107,4 @@ see  [Create Folders](how-to-create-folders)  for more details.
 :::
 ::::
 
-:::{note}
-
-When in local-only mode, some functionality of ``datashuttle`` is lost.
-
-It will not be possible to:
-- transfer data, which requires passing configs related to a centrally-stored project.
-- Any method that exposes a ``include_central`` argument will always set this to ``False``.
-For example, validation will only ever be performed on the local project.
-
-See [](make-a-full-project_target) for more information on setting up for data transfer.
 :::
diff --git a/docs/source/pages/user_guides/create-folders.md b/docs/source/pages/user_guides/create-folders.md
@@ -1,5 +1,5 @@
 (how-to-create-folders)=
-# How to Create Folders
+# Create Folders
 
 ``datashuttle`` automates project folder creation and validation
 according to the [NeuroBlueprint](https://neuroblueprint.neuroinformatics.dev/).
@@ -40,7 +40,7 @@ Now, let's get started with folder creation!
 ## Creating project folders
 
 The project-name folder is located at the **local path**
-specified when [setting up the project](make-a-full-project_target).
+specified when [setting up the project](set-up-configs-for-transfer_).
 
 We will now create subject, session and
 datatype folders within a `rawdata` top-level folder.
diff --git a/docs/source/pages/user_guides/index.md b/docs/source/pages/user_guides/index.md
@@ -8,7 +8,7 @@
 :gutter: 4
 
 
-:::{grid-item-card} {fas}`desktop;sd-text-primary` Validate
+:::{grid-item-card} {fas}`desktop;sd-text-primary` Validate Folders
 :link: validate
 :link-type: doc
 :class-img-top: tutorial-link-image
@@ -25,6 +25,14 @@ Create [NeuroBlueprint](https://neuroblueprint.neuroinformatics.dev/latest/index
 :::
 
 
+:::{grid-item-card} {fas}`desktop;sd-text-primary` Set up Configs for Transfer
+:link: set-up-configs-for-transfer
+:link-type: doc
+
+Set up a project for data-transfer
+:::
+
+
 :::{grid-item-card} {fas}`desktop;sd-text-primary` Transfer Data
 :link: transfer-data
 :link-type: doc
@@ -65,7 +73,7 @@ A handy feature for template subject and session names.
 
 validate
 create-folders
-make-a-full-project
+set-up-configs-for-transfer
 transfer-data
 update-configs
 read-logs
diff --git a/docs/source/pages/user_guides/read-logs.md b/docs/source/pages/user_guides/read-logs.md
@@ -1,6 +1,6 @@
 (how-to-read-the-logs)=
 
-# How to Read the Logs
+# Read the Logs
 
 ``datashuttle`` stores detailed logs when commands that
 create folders, change project configs or perform data transfers are run.
diff --git a/docs/source/pages/user_guides/set-up-configs-for-transfer.md b/docs/source/pages/user_guides/set-up-configs-for-transfer.md
@@ -1,8 +1,9 @@
-(make-a-full-project_target)=
-# How to Make a Full Project
+(set-up-configs-for-transfer_)=
+# Set up configurations for transfer
 
 This guide will cover all you need to know for setting up a new project
-in ``datashuttle``.
+in ``datashuttle`` for transfer. If you just want to create and validate
+folders, see [set up a local project](set-up-a-local-project).
 
 First, make sure you have
 [installed and launched ``datashuttle``](how-to-install).
diff --git a/docs/source/pages/user_guides/transfer-data.md b/docs/source/pages/user_guides/transfer-data.md
@@ -1,9 +1,18 @@
 (how-to-transfer-data)=
-# How to Transfer Data
+# Transfer Data
+
+:::{note}
+
+This guide assumes that you have already set up your project
+for data transfer. Please see [set up a project for transfer](set-up-a-local-project)
+for details.
+
+:::
 
 ``datashuttle`` facilitates convenient transfer of data between
 local and central storage machines.
 
+
 This includes:
 - 'Uploading' data from an acquisition machine to central data storage.
 - 'Downloading' subsets of data from central storage to analysis machines.
@@ -22,7 +31,6 @@ This includes:
 :::{admonition} Transfer Direction
 :class: note
 
-
 In ``datashuttle``, the *upload* refers to transfer
 from a local to the central machine.
 *Download* refers to transfer from the central machine to a local machine.
@@ -76,7 +84,7 @@ to central storage while existing files will be ignored.
 ```
 <br>
 
-To transfer the entire project navitgate to the `Transfer tab`. The
+To transfer the entire project navigate to the `Transfer tab`. The
 `All` button is selected to transfer the entire project.
 
 Click `Transfer` to begin.
diff --git a/docs/source/pages/user_guides/update-configs.md b/docs/source/pages/user_guides/update-configs.md
@@ -1,5 +1,5 @@
 
-# How to Update Configs
+# Update Configs
 
 The project configs can be updated at any time following the initial setup.
 
diff --git a/docs/source/pages/user_guides/use-name-templates.md b/docs/source/pages/user_guides/use-name-templates.md
@@ -1,6 +1,6 @@
 (how-to-use-name-templates)=
 
-# How to use Name Templates
+# Name Templates
 
 Validation in ``datashuttle`` is by default restricted to the
 NeuroBlueprint specification. Any subject or session names
diff --git a/docs/source/pages/user_guides/validate.md b/docs/source/pages/user_guides/validate.md
@@ -109,7 +109,7 @@ folders across 'local' and 'central' before validation. This is useful check aga
 (e.g. `sub-001` vs `sub-02`) and duplicate names (e.g. ``sub-001`` and ``sub-001_date-20240101``) across
 the 'local' and 'central' project.
 
-To perform this type of validation, connection configurations [must be set](make-a-full-project_target).
+To perform this type of validation, connection configurations [must be set](set-up-configs-for-transfer_).
 The ``include_central`` argument must be set to ``True``:
 
 ```python
