diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 37c5d7b..36e24ab 100644 --- 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/
`) may contain several markdown files, with each file corresponding to a specific long-form guide. There are also `docs/source/
/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/
/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 index 6dd895f..9246bed 100644 --- 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 index 21df6a9..6a9430d 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -3,4 +3,5 @@ pydata-sphinx-theme myst-parser numpydoc nbsphinx -linkify-it-py \ No newline at end of file +linkify-it-py +sphinx-design diff --git a/docs/source/conf.py b/docs/source/conf.py index 4bcb207..9e8ccf2 100644 --- 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"], -} \ No newline at end of file +} + +# 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 deleted file mode 100644 index dd4b854..0000000 --- a/docs/source/data_analysis/Behaviour.md +++ /dev/null @@ -1,6 +0,0 @@ -# Behaviour - -## SLEAP - -### Pip install fails for SLEAP on Windows 10 -SLEAP lists several [installation methods](https://sleap.ai/develop/installation.html#installation-methods). People have reported problems with the `pip install` method on windows. The `conda` method - `conda create -y -n sleap -c sleap -c nvidia -c conda-forge sleap=1.2.8` - works well on Linux and Windows (as of October 2022). For ARM64 silicon Macs, follow the [M1-specific installation instructions](https://sleap.ai/develop/installation.html#m1-macs). diff --git a/docs/source/data_analysis/Electrophysiology.md b/docs/source/data_analysis/Electrophysiology.md deleted file mode 100644 index d59845f..0000000 --- a/docs/source/data_analysis/Electrophysiology.md +++ /dev/null @@ -1 +0,0 @@ -# Electrophysiology \ No newline at end of file diff --git a/docs/source/data_analysis/Histology.md b/docs/source/data_analysis/Histology.md deleted file mode 100644 index f75a5bb..0000000 --- a/docs/source/data_analysis/Histology.md +++ /dev/null @@ -1 +0,0 @@ -# Histology \ No newline at end of file diff --git a/docs/source/data_analysis/Imaging.md b/docs/source/data_analysis/Imaging.md deleted file mode 100644 index 59bcb98..0000000 --- a/docs/source/data_analysis/Imaging.md +++ /dev/null @@ -1 +0,0 @@ -# Imaging \ No newline at end of file diff --git a/docs/source/data_analysis/index.md b/docs/source/data_analysis/index.md index 933f1a7..9a45371 100644 --- 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 index ae81676..5160551 100644 --- 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 index 4d0332e..695eafc 100644 --- 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 b/docs/source/programming/Cookiecutter-cruft.md similarity index 96% rename from docs/source/programming/Python.md rename to docs/source/programming/Cookiecutter-cruft.md index 0664e31..b2173e3 100644 --- a/docs/source/programming/Python.md +++ b/docs/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 b/docs/source/programming/Mount-ceph-ubuntu.md similarity index 75% rename from docs/source/programming/Linux.md rename to docs/source/programming/Mount-ceph-ubuntu.md index 75add04..c5ed1fa 100644 --- a/docs/source/programming/Linux.md +++ b/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 b/docs/source/programming/SSH-vscode.md similarity index 90% rename from docs/source/programming/IDEs.md rename to docs/source/programming/SSH-vscode.md index d4c5621..2728fd4 100644 --- a/docs/source/programming/IDEs.md +++ b/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 new file mode 100644 index 0000000..1a3d984 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/source/programming/VersionControl.md b/docs/source/programming/VersionControl.md deleted file mode 100644 index b9e3484..0000000 --- a/docs/source/programming/VersionControl.md +++ /dev/null @@ -1,8 +0,0 @@ -# Version Control - -## GitHub - -### How to detach a forked repo -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/index.md b/docs/source/programming/index.md index 737155f..96d2ab3 100644 --- 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 ``` \ No newline at end of file