Restructure website (#37)

* reorganise programming section * restructure data analysis section * added sphinx-design to requirements * Rewrote homepage * udpated repo readme * updated contributing guide * added warning about guide names starting with How To * hide TOC on homepage * removed coming soon section * reduced TOC depth in the main sections * hide the show source button
neuroinformatics-unit · Jun 26, 2023 · 6266b5a · 6266b5a
1 parent c3a7ff5
commit 6266b5a
Show file tree

Hide file tree

Showing 17 changed files with 99 additions and 78 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,36 +1,41 @@
 # How to contribute to this website
 
 ## Website structure
-
 The website is structured in three high-level sections, represented by folders in the `docs/source` directory:
 - Data Analysis
 - Programming
-- Guides
+- Open Science
 
-Each section is further divided into sub-sections, each corresponding to a different markdown file in `docs/source/{section}` directory. There are also `docs/source/{section}/index.md` files, which are used to create the tables of contents for each section.
+Each section directory (`docs/source/<section>`) may contain several markdown files, with each file corresponding to a specific long-form guide. There are also `docs/source/<section>/index.md` files, which are used to create the tables of contents for each section.
 
-## Adding new content
+## Adding a long-form guide
+To add a new guide, create a new markdown file in the appropriate section directory, and make sure to start it with a level-1 heading. Remember to also add the new file to the table of contents in the corresponding`docs/source/<section>/index.md` file.
 
-To add a new sub-section, create a new markdown file in the appropriate section directory, and make sure to start it with a level-1 heading. Remember to also add the new file to the table of contents in the corresponding`docs/source/{section}/index.md` file.
+## Adding a small tip
+If the content you want to add is not long enough to warrant a full guide, for example a small tip or a quick solution to a common problem, you can add it to a `Troubleshooting.md` file in the appropriate section directory. For an example see `docs/source/programming/Troubleshooting.md`. Each small tip should start with a level-2 heading.
 
-To add entries to an existing sub-section, simply add new level-2/3 headings to the right markdown file, as appropriate.
+> **warning**
+> 
+> Since the website is already named "HowTo", please avoid starting your guides/tips with "How to ...".
+> For example, instead of "How to detach a forked repo on GitHub", use "Detach a forked repo on GitHub".
   
 ## GitHub workflow
 * Clone the GitHub repository, and create your `new_branch`.
 * Edit the website and commit your changes to the `new_branch`.
-* Push the `new_branch` to GitHub and create a pull request. This will automatically trigger a [GitHub Action](https://github.com/ammaraskar/sphinx-action) that checks if the website still builds correctly.
-* If the checks pass, assign someone to review your changes. 
-* When the reviewer merges your changes into the `main` branch, a different [GitHub Action](https://github.com/peaceiris/actions-gh-pages) will be triggered, which will build the website and publish it to the `gh-pages` branch.
+* Push the `new_branch` to GitHub and create a draft pull request. This will automatically trigger a [GitHub action](https://github.com/neuroinformatics-unit/actions/tree/main/build_sphinx_docs) that checks if the website still builds correctly.
+* If the checks pass, mark the pull request as ready to review assign someone to review your changes. 
+* When the reviewer merges your changes into the `main` branch, a different [GitHub action](https://github.com/neuroinformatics-unit/actions/tree/main/deploy_sphinx_docs) will be triggered, which will build the website and publish it to the `gh-pages` branch.
 * The updated website should be available at [howto.neuroinformatics.dev](https://howto.neuroinformatics.dev)
 
 > **note**
+> 
 > If you wish to view the website locally, before you push it, you can do so by running the following commands from the root of the repository.
 > ```bash
 > # First time only
 > pip install -r docs/requirements.txt
 > sphinx-build docs/source docs/build
 >
-> # Every time you want to build the website
+> # Every time you want to update the local build
 > rm -rf docs/build && sphinx-build docs/source docs/build
 >```
 >You can view the local build at `docs/build/index.html`
diff --git a/README.md b/README.md
@@ -1,7 +1,12 @@
 # Neuroinformatics Unit HowTo
 
+[![Website shields.io](https://img.shields.io/website-up-down-green-red/https/howto.neuroinformatics.dev.svg)](https://howto.neuroinformatics.dev)
+[![made-with-sphinx-doc](https://img.shields.io/badge/Made%20with-Sphinx-1f425f.svg)](https://www.sphinx-doc.org/)
+
 Source code for the [Neuroinformatics Unit HowTo](https://howto.neuroinformatics.dev/) website.
 
-On this website, we keep track of solutions to common issues arising when using software tools for neuroscience research (whether made by the Neuroinformatics Unit or not). The information is primarily aimed at researchers at the [Sainsbury Wellcome Centre (SWC)](https://www.sainsburywellcome.org/web/) and [Gatsby Computational Neuroscience Unit (GCNU)](https://www.ucl.ac.uk/gatsby/gatsby-computational-neuroscience-unit), though most of it should be useful to neuroscientists in general.
+On this website, we keep track of long-form how-to guides as well as collections of small tips and tricks related to data analysis and software development in neuroscience.
+
+The information is primarily aimed at researchers at the [Sainsbury Wellcome Centre (SWC)](https://www.sainsburywellcome.org/web/) and [Gatsby Computational Neuroscience Unit (GCNU)](https://www.ucl.ac.uk/gatsby/gatsby-computational-neuroscience-unit), though most of it should be useful to neuroscientists in general.
 
 If you wish to edit the website, please read the [contributing guide](CONTRIBUTING.md) first.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -3,4 +3,5 @@ pydata-sphinx-theme
 myst-parser
 numpydoc
 nbsphinx
-linkify-it-py
+linkify-it-py
+sphinx-design
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -37,6 +37,7 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
+    'sphinx_design',
     'myst_parser',
     'numpydoc',
     'nbsphinx',
@@ -120,4 +121,7 @@
     },
     "footer_start": ["footer_start"],
     "footer_end": ["footer_end"],
-}
+}
+
+# Hide the "Show Source" button
+html_show_sourcelink = False
diff --git a/docs/source/data_analysis/Behaviour.md b/docs/source/data_analysis/Behaviour.md
diff --git a/docs/source/data_analysis/Electrophysiology.md b/docs/source/data_analysis/Electrophysiology.md
diff --git a/docs/source/data_analysis/Histology.md b/docs/source/data_analysis/Histology.md
diff --git a/docs/source/data_analysis/Imaging.md b/docs/source/data_analysis/Imaging.md
diff --git a/docs/source/data_analysis/index.md b/docs/source/data_analysis/index.md
@@ -1,15 +1,10 @@
 # Data Analysis
 
-Issues relating to data analysis in neuroscience are grouped into sections corresponding to data *modalities*.
-Each *modality* is further subdivided into subsections corresponding to specific *tools*.
+Guides related to the analysis of neuroscientific data, spanning a wide range of data types such as electrophysiology, behaviour, calcium imaging, histology, etc. The focus may be on the use of specific software tools, or on more general analysis tasks and concepts.
 
 ```{toctree}
-:maxdepth: 2
+:maxdepth: 1
 
-Behaviour
-Electrophysiology
-Imaging
-Histology
 ```
 
 
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -1,12 +1,43 @@
 # Neuroinformatics Unit HowTo
 
-On this website, you can find solutions to common issues that you may encounter when using software tools for neuroscience research (whether made by the Neuroinformatics Unit or not).
+On this website you can find long-form how-to guides as well as collections of small tips and tricks related to data analysis and software development in neuroscience.
+
+The webiste is maintained by members of the [Neuroinformatics Unit](https://neuroinformatics.dev). The information is primarily aimed at researchers at the [Sainsbury Wellcome Centre (SWC)](https://www.sainsburywellcome.org/web/) and [Gatsby Computational Neuroscience Unit (GCNU)](https://www.ucl.ac.uk/gatsby/gatsby-computational-neuroscience-unit), though most of it should be useful to neuroscientists in general.
+
+
+## Main sections
+The guides are organised into three main sections:
+
+::::{grid} 1 2 2 3
+:gutter: 3
+
+:::{grid-item-card} {fas}`chart-simple;sd-text-primary` Data Analysis
+:link: data_analysis/index
+:link-type: doc
+
+Guides related to tools and approaches for analysing neuroscientific data.
+:::
+
+:::{grid-item-card} {fas}`code;sd-text-primary` Programming
+:link: programming/index
+:link-type: doc
+
+General coding and software development issues.
+:::
+
+:::{grid-item-card} {fas}`lock-open;sd-text-primary` Open Science
+:link: open_science/index
+:link-type: doc
+
+How to effectively share your code and data.
+:::
+
+::::
 
-The information is primarily aimed at researchers at the [Sainsbury Wellcome Centre (SWC)](https://www.sainsburywellcome.org/web/) and [Gatsby Computational Neuroscience Unit (GCNU)](https://www.ucl.ac.uk/gatsby/gatsby-computational-neuroscience-unit), though most of it should be useful to neuroscientists in general.
 
 ```{toctree}
 :maxdepth: 2
-:caption: Sections
+:hidden:
 
 data_analysis/index
 programming/index

diff --git a/docs/source/open_science/index.md b/docs/source/open_science/index.md
@@ -3,7 +3,7 @@
 A collection of long-form guides on topics related to open science.
 
 ```{toctree}
-:maxdepth: 2
+:maxdepth: 1
 
 Licensing
 Data-sharing

diff --git a/docs/source/programming/Python.md → .../source/programming/Cookiecutter-cruft.md b/docs/source/programming/Python.md → .../source/programming/Cookiecutter-cruft.md
@@ -1,6 +1,4 @@
-# Python
-
-## Update cookiecutter-generated files with cruft
+# Update cookiecutter-generated files with cruft
 
 Ref: [original docs](https://cruft.github.io/cruft/) and [github repo](https://github.com/cruft/cruft).
 

diff --git a/docs/source/programming/Linux.md → docs/source/programming/Mount-ceph-ubuntu.md b/docs/source/programming/Linux.md → docs/source/programming/Mount-ceph-ubuntu.md
@@ -1,28 +1,13 @@
-# Linux and command line
-
-## Ubuntu
-
-### Distro update error
-This is an error that appeared when updating to a new Ubuntu distribution.
-Error msg: Software Updater - Not all updates can be installed.   
-Solution: `sudo apt-get dist-upgrade`
-
-### Terminal is not opening after installing a new Python version
-If you installed a new Python version without the use of `conda`, there might be a mismatch in the python naming in a bin file.   
-If it's possible open terminal through vscode or open a virtual terminal (VT) with CTRL + ALT + F3 and run `gnome-ternimal`.
-Does it throw a Python error? If yes run `sudo nano /usr/bin/gnome-terminal` and change `#!/usr/bin/python3` to `#!/usr/bin/python3.10` if the version you're currently using is 3.10.  
-Exit the VT via CTRL + ALT + F2.
-
-### How to mount ceph storage on Ubuntu
+# Mount ceph storage on Ubuntu
 In this example, we will **permanently** mount the `neuroinformatics` partition of `ceph`. The same procedure can be used to mount other partitions, such as those belonging to particular labs or projects.
 
 The following instructions have been tested on **Ubuntu 20.04 LTS**.
 
-#### Prerequisites
+## Prerequisites
 - Administrator rights (`sudo`) on the local Ubuntu machine
 - `cifs-utils` installed via `sudo apt-get install cifs-utils`
 
-#### Store your SWC credentials
+## Store your SWC credentials
 First, create a file to store your SWC login credentials and save it in your home directory.
 You can do that on the terminal via `nano ~/.smb_swc`. 
 
@@ -47,14 +32,14 @@ This will ensure the file is readable and writable only by the owner (you).
 However, if someone gets access to your machine with your user logged in, they will still be able to read the SWC password.
 :::
 
-#### Create a mount point
+## Create a mount point
 Create a directory to mount the storage to. Sensible places to do this on Ubuntu would be in `/mnt` or `/media`. In the example below, we will use `/media/ceph-neuroinformatics`.
 
 ```bash 
 sudo mkdir /media/ceph-neuroinformatics
 ```
 
-#### Edit the fstab file
+## Edit the fstab file
 This will allow you to mount the storage automatically on boot. Before editing the file, make a backup of it, just in case.
 ```bash
 sudo cp /etc/fstab /etc/fstab.bak
@@ -74,12 +59,12 @@ Make sure to replace the following:
 
 Save the file and exit.
 
-#### Mount the storage
+## Mount the storage
 You can now mount the storage by running `sudo mount -a`. If you get an error, check the `fstab` file for typos. If you get no error, you should be able to see the mounted storage by running `df -h`.
 
 The next time you reboot your machine, the storage should be mounted automatically.
 
-#### Unmount the storage
+## Unmount the storage
 To unmount the storage, run `sudo umount /media/ceph-neuroinformatics` (or whatever your mount point is).
 
 To permanently unmount the storage, remove the lines you added to the `fstab` file and run `sudo mount -a` again.
diff --git a/docs/source/programming/IDEs.md → docs/source/programming/SSH-vscode.md b/docs/source/programming/IDEs.md → docs/source/programming/SSH-vscode.md
@@ -1,9 +1,4 @@
-# IDEs
-*Integrated Development Environments*
-
-## VSCode
-
-### SSH into an unmanaged machine from remote
+# SSH into an unmanaged machine using VSCode
 > **_Example Usecase:_**  When working from home, connect from you local Mac to the SWC office Linux machine
 
 In your local machine `cd` and ` open .ssh/config` and append the following configurations:

diff --git a/docs/source/programming/Troubleshooting.md b/docs/source/programming/Troubleshooting.md
@@ -0,0 +1,17 @@
+# Troubleshooting
+Small problems and their solutions.
+
+## Ubuntu distribution update error
+This is an error that appeared when updating to a new Ubuntu distribution.
+Error msg: Software Updater - Not all updates can be installed.   
+Solution: `sudo apt-get dist-upgrade`
+
+## Terminal is not opening after installing a new Python version
+If you installed a new Python version without the use of `conda`, there might be a mismatch in the python naming in a bin file.   
+If it's possible open terminal through vscode or open a virtual terminal (VT) with CTRL + ALT + F3 and run `gnome-ternimal`.
+Does it throw a Python error? If yes run `sudo nano /usr/bin/gnome-terminal` and change `#!/usr/bin/python3` to `#!/usr/bin/python3.10` if the version you're currently using is 3.10.  
+Exit the VT via CTRL + ALT + F2.
+
+## Detach a forked repo on GitHub
+If you forked a repo and want to detach it from the original repo, use the [Github chatbot-virtual-assistant](https://support.github.com/contact?tags=rr-forks&subject=Detach%20Fork&flow=detach_fork).
+Follow the instructions and wait for the response.
diff --git a/docs/source/programming/VersionControl.md b/docs/source/programming/VersionControl.md
diff --git a/docs/source/programming/index.md b/docs/source/programming/index.md
@@ -1,12 +1,14 @@
 # Programming
 
-General programming and software development issues, tips and tricks.
+Guides related to general coding and software development issue, such as version control, programming environments, IDEs, Linux, the command line, etc.
+
+Small tips and tricks that do not warrant a long-form guide can be found in the [Troubleshooting](Troubleshooting.md) section.
 
 ```{toctree}
-:maxdepth: 2
+:maxdepth: 1
 
-Linux
-IDEs
-VersionControl
-Python
+SSH-vscode
+Mount-ceph-ubuntu
+Cookiecutter-cruft
+Troubleshooting
 ```