Rework of docs before v0.4.0 (#367)

* Remove old pages.

* Reduce number of build warnings.

* Tidying up the docs

* Tidying up getting started.

* Update password entry for TTY terminal.

* Finished checking all docs.

* Apply feedback from #362.

Author: JoeZiminski

datashuttle/datashuttle.py

@@ -1431,7 +1431,7 @@ def _load_persistent_settings(self) -> Dict:
 
     def _update_settings_with_new_canonical_keys(self, settings: Dict):
         """
-        Perform a check on the top-level keys within persistent settings.
+        Perform a check on the keys within persistent settings.
         If they do not exist, persistent settings is from older version
         and the new keys need adding.
         If changing keys within the top level (e.g. a dict entry in

datashuttle/utils/ssh.py

@@ -128,19 +128,25 @@ def setup_ssh_key(
     log : log if True, logger must already be initialised.
     """
     if not sys.stdin.isatty():
-        utils.log_and_raise_error(
-            "Attempting to run outside of a TTY terminal. "
-            "This may happen if attempting to run in an IDE console. "
-            "`getpass` (used for ssh password input) cannot run. "
-            "Try using Python from the operating system "
-            "terminal to run this function.",
-            RuntimeError,
+        proceed = input(
+            "\nWARNING!\nThe next step is to enter a password, but it is not possible\n"
+            "to hide your password while entering it in the current terminal.\n"
+            "This can occur if running the command in an IDE.\n\n"
+            "Press 'y' to proceed to password entry. "
+            "The characters will not be hidden!\n"
+            "Alternatively, run ssh setup after starting Python in your "
+            "system terminal \nrather than through an IDE: "
+        )
+        if proceed != "y":
+            return
+        password = input(
+            "Please enter your password. Characters will not be hidden: "
+        )
+    else:
+        password = getpass.getpass(
+            "Please enter password to your central host to add the public key. "
+            "You will not have to enter your password again."
         )
-
-    password = getpass.getpass(
-        "Please enter password to your central host to add the public key. "
-        "You will not have to enter your password again."
-    )
 
     add_public_key_to_central_authorized_keys(cfg, password)
 

docs/source/conf.py

@@ -77,11 +77,6 @@
 #toc_object_entries_show_parents = "all"
 html_show_sourcelink = False
 
-#html_sidebars = {  this is not working...
-#  "index": [],
-#  "**": [],
-#}
-
 # Ignore links that do not work with github actions link checking
 # https://github.com/neuroinformatics-unit/actions/pull/24#issue-1978966182
 linkcheck_anchors_ignore_for_url = [
@@ -125,6 +120,10 @@
 
 html_favicon = "_static/logo_light.png"
 
+html_sidebars = {
+  "**": []
+}
+
 # Customize the theme
 html_theme_options = {
     "icon_links": [
@@ -148,7 +147,7 @@
         },
     ],
     "logo": {
-        "text": f"Datashuttle v{release}",
+        "text": f"datashuttle v{release}",
         "image_light": "_static/logo_light.png",
         "image_dark": "_static/logo_dark.png",
     },

docs/source/index.md

@@ -3,7 +3,7 @@
 {.center}
 # **datashuttle**
 
-<p style="text-align: center; font-size: 22px;">The tool to automate neuroscience project folder creation and transfer.</p>
+<p style="text-align: center; font-size: 22px;">The tool to automate neuroscience project folder creation, validation and transfer.</p>
 
 ```{image} _static/datashuttle-overview-light.png
 :alt: My Logo
@@ -40,17 +40,18 @@ Short guides on specific actions.
 :link: pages/api_index
 :link-type: doc
 
-Full Python API reference.
+Full Python reference.
 :::
 ::::
 
-Datashuttle creates and validates projects standardised to the
+**datashuttle** creates and validates projects standardised to the
 [NeuroBlueprint](https://neuroblueprint.neuroinformatics.dev)
 specification.
 
 Dive right into **datashuttle** with our
-[Getting Started Tutorial]((tutorial-getting-started)=)
-or targeted [How-To Guides](how-tos).
+[Getting Started Tutorial](tutorial-getting-started)
+or targeted [How-To Guides](how-tos).  \
+It can be used through a graphical interface or Python API.
 
 Don't hesitate to get in contact through our
 [GitHub Issues](https://github.com/neuroinformatics-unit/datashuttle/issues)