[Documentation] Improve documentation (#207)

* Start reworking docs. * Update version handling in conf.py * Fix reference toctrees. * Small fixes. * Fixes to code examples for transfer. * Typo fix. Co-authored-by: Niko Sirmpilatze <[email protected]> * Typo fix. Co-authored-by: Niko Sirmpilatze <[email protected]> * Typo fix. Co-authored-by: Niko Sirmpilatze <[email protected]> * Typo fix. Co-authored-by: Niko Sirmpilatze <[email protected]> * Typo fix. Co-authored-by: Niko Sirmpilatze <[email protected]> * Typo fix. Co-authored-by: Niko Sirmpilatze <[email protected]> * Typo fix. Co-authored-by: Niko Sirmpilatze <[email protected]> * Typo fix. Co-authored-by: Niko Sirmpilatze <[email protected]> * Update installation instructions. * Update bad make-folders example. * Improve zsh warning for @*@ tag. * Use explicit targets to link CLI and API reference. * Swap dot for info on example. * Use real windows path in example. * Rename 'Get Started' to 'User Guide'. * Small fixes. --------- Co-authored-by: Niko Sirmpilatze <[email protected]>
neuroinformatics-unit · Oct 25, 2023 · d0269b7 · d0269b7
1 parent c02a68f
commit d0269b7
Show file tree

Hide file tree

Showing 5 changed files with 800 additions and 308 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -19,8 +19,11 @@
 project = "datashuttle"
 copyright = "2022, Neuroinformatics Unit"
 author = "Neuroinformatics Unit"
+
+# Retrieve the version number from the package
 try:
     release = setuptools_scm.get_version(root="../..", relative_to=__file__)
+    release = release.split(".dev")[0]  # remove dev tag and git hash
 except LookupError:
     # if git is not initialised, still allow local build
     # with a dummy version
@@ -72,7 +75,7 @@
 #toc_object_entries_show_parents = "all"
 html_show_sourcelink = False
 
-#html_sidebars = {  # grr this is not working...
+#html_sidebars = {  this is not working...
 #  "index": [],
 #  "**": [],
 #}
@@ -130,20 +133,20 @@
         }
     ],
     "logo": {
-        "text": f"DataShuttle. version: {release}",
+        "text": f"Datashuttle v{release}",
         "image_light": "_static/logo_light.png",
         "image_dark": "_static/logo_dark.png",
     },
     "footer_start": ["footer_start"],
     "footer_end": ["footer_end"],
-#    "show_toc_level": 2  # sidebar levels that are expanded before scrolling
+    "show_toc_level": 2,  # sidebar levels that are expanded before scrolling
 #    "secondary_sidebar_items": [],
-#    "page_sidebar_items": [],
+ #   "page_sidebar_items": [],
 }
 
 # Redirect the webpage to another URL
 # Sphinx will create the appropriate CNAME file in the build directory
 # The default is the URL of the GitHub pages
 # https://www.sphinx-doc.org/en/master/usage/extensions/githubpages.html
 github_user = "JoeZiminski"
-html_baseurl = "https://datashuttle.neuroinformatics.dev/"  # f"http(s)://{github_user}.github.io/{project}"
+html_baseurl = "https://datashuttle.neuroinformatics.dev/"
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -13,7 +13,7 @@ Any feedback is much appreciated, please open at [GitHub Issue](https://github.c
 ::::{grid} 1 2 2 3
 :gutter: 3
 
-:::{grid-item-card} Get Started
+:::{grid-item-card} User Guide
 :link: pages/documentation
 :link-type: doc
 

diff --git a/docs/source/pages/api_index.rst b/docs/source/pages/api_index.rst
@@ -1,3 +1,5 @@
+.. _API_Reference:
+
 API Reference
 -----------------
 

diff --git a/docs/source/pages/cli_index.rst b/docs/source/pages/cli_index.rst
@@ -1,3 +1,5 @@
+.. _CLI_Reference:
+
 CLI Reference
 -----------------