diff --git a/.github/workflows/docs_build_and_deploy.yml b/.github/workflows/docs_build_and_deploy.yml index 1ebfe4d..85d3aae 100644 --- a/.github/workflows/docs_build_and_deploy.yml +++ b/.github/workflows/docs_build_and_deploy.yml @@ -15,8 +15,20 @@ on: workflow_dispatch: jobs: + codespell: + name: Check for spelling errors + permissions: + contents: read + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Codespell + uses: codespell-project/actions-codespell@v2 + build_sphinx_docs: name: Build Sphinx Docs + needs: codespell runs-on: ubuntu-latest steps: - uses: neuroinformatics-unit/actions/build_sphinx_docs@v2 diff --git a/.gitignore b/.gitignore index 289cfee..aedc8d7 100644 --- a/.gitignore +++ b/.gitignore @@ -81,4 +81,3 @@ venv/ # written by setuptools_scm **/_version.py - diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..71f9f50 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,19 @@ +exclude: 'conf.py' + +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.3.0 + hooks: + - id: check-docstring-first + - id: check-executables-have-shebangs + - id: check-merge-conflict + - id: check-toml + - id: end-of-file-fixer + - id: mixed-line-ending + args: [--fix=lf] + - id: requirements-txt-fixer + - id: trailing-whitespace + - repo: https://github.com/codespell-project/codespell + rev: v2.2.5 + hooks: + - id: codespell diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 36e24ab..26133a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,20 +15,20 @@ To add a new guide, create a new markdown file in the appropriate section direct 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. > **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 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. +* 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 diff --git a/docs/make.bat b/docs/make.bat index 747ffb7..dc1312a 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -1,35 +1,35 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt index 6a9430d..e6f6522 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,7 +1,7 @@ -sphinx -pydata-sphinx-theme +linkify-it-py myst-parser -numpydoc nbsphinx -linkify-it-py +numpydoc +pydata-sphinx-theme +sphinx sphinx-design diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css index f954850..0163401 100644 --- a/docs/source/_static/css/custom.css +++ b/docs/source/_static/css/custom.css @@ -28,4 +28,4 @@ html[data-theme=light] { display: flex; flex-wrap: wrap; justify-content: space-between; -} \ No newline at end of file +} diff --git a/docs/source/_templates/footer_start.html b/docs/source/_templates/footer_start.html index 2ab9d25..0c9f776 100644 --- a/docs/source/_templates/footer_start.html +++ b/docs/source/_templates/footer_start.html @@ -6,4 +6,4 @@ {{ _("Built with the") }} PyData Sphinx Theme {{ theme_version }}. -

\ No newline at end of file +

diff --git a/docs/source/data_analysis/index.md b/docs/source/data_analysis/index.md index 9a45371..0e020c6 100644 --- a/docs/source/data_analysis/index.md +++ b/docs/source/data_analysis/index.md @@ -6,5 +6,3 @@ Guides related to the analysis of neuroscientific data, spanning a wide range of :maxdepth: 1 ``` - - diff --git a/docs/source/index.md b/docs/source/index.md index 5160551..109a66f 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -2,7 +2,7 @@ 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. +The website 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 diff --git a/docs/source/open_science/Data-sharing.md b/docs/source/open_science/Data-sharing.md index 1a31ffb..b4d0955 100644 --- a/docs/source/open_science/Data-sharing.md +++ b/docs/source/open_science/Data-sharing.md @@ -17,7 +17,7 @@ Data is key to neuroscience, and it should be shared for maximal utility. There ## Requirements -Currently, SWC does not have any specific code and data sharing requirements, but your funder or publisher may do. +Currently, SWC does not have any specific code and data sharing requirements, but your funder or publisher may do. **Ideally, all data and code will be shared in such a way that any other researcher could easily reproduce key figures from a publication, and build on those data and software in their own research.** @@ -25,7 +25,7 @@ Currently, SWC does not have any specific code and data sharing requirements, bu ## Code Original code can be hosted in a public GitHub/GitLab repository, hosted on an organisational account (i.e. not an individual account). This could be the [SWC organisation](https://github.com/SainsburyWellcomeCentre), or that of a particular team, lab or collaboration. To enable re-use, code should include an [appropriate license](https://howto.neuroinformatics.dev/guides/Licensing.html). -To ensure a permanent archive of the code associated with a publication a [DOI](https://www.doi.org/) should be created (e.g. using [Zenodo](https://docs.github.com/en/repositories/archiving-a-github-repository/referencing-and-citing-content)). +To ensure a permanent archive of the code associated with a publication a [DOI](https://www.doi.org/) should be created (e.g. using [Zenodo](https://docs.github.com/en/repositories/archiving-a-github-repository/referencing-and-citing-content)). ## Data ### Repository @@ -75,4 +75,3 @@ If you have any technical questions about sharing data or code, please contact a | NeuroMorpho |https://neuromorpho.org/ |Neuronal morphologies | | Cell Image Library |http://ccdb.ucsd.edu/home |Cell images | | ModelDB |https://senselab.med.yale.edu/ModelDB/ |Computational neuroscience models | - diff --git a/docs/source/open_science/Licensing.md b/docs/source/open_science/Licensing.md index 248240c..b6143a2 100644 --- a/docs/source/open_science/Licensing.md +++ b/docs/source/open_science/Licensing.md @@ -3,9 +3,9 @@ ## Disclaimer **This document was not written by lawyers, and does not represent legal advice.** -This guide was written by the [Neuroinformatics Unit](https://neuroinformatics.dev/) to help 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) at [University College London (UCL)](https://www.ucl.ac.uk/) choose a license for their software. +This guide was written by the [Neuroinformatics Unit](https://neuroinformatics.dev/) to help 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) at [University College London (UCL)](https://www.ucl.ac.uk/) choose a license for their software. It does not represent official guidance by SWC, GCNU or UCL. -In particular this is not advice about intellectual property, but rather the practicalities of adding a license to your software. +In particular this is not advice about intellectual property, but rather the practicalities of adding a license to your software. For more information, SWC/GCNU researchers should consult the SWC/GCNU and UCL documentation about intellectual property or contact [UCL Business](https://www.uclb.com/) if you think your software may have commercial potential (before release). ## Summary diff --git a/docs/source/open_science/index.md b/docs/source/open_science/index.md index 695eafc..8e570e3 100644 --- a/docs/source/open_science/index.md +++ b/docs/source/open_science/index.md @@ -7,4 +7,4 @@ A collection of long-form guides on topics related to open science. Licensing Data-sharing -``` \ No newline at end of file +``` diff --git a/docs/source/programming/Cookiecutter-cruft.md b/docs/source/programming/Cookiecutter-cruft.md index 4e9d069..8a72753 100644 --- a/docs/source/programming/Cookiecutter-cruft.md +++ b/docs/source/programming/Cookiecutter-cruft.md @@ -3,7 +3,7 @@ Ref: [original docs](https://cruft.github.io/cruft/) and [github repo](https://github.com/cruft/cruft). ## Setup: `cruft link` -Install: `pip install cruft`. +Install: `pip install cruft`. If this is your first time using `cruft`, you have to set it up using the `cruft link` command. You have to specify the URL of your cookiecutter on GitHub. @@ -38,6 +38,6 @@ When `cruft update` is done, you will notice that the `.cruft.json` file has bee `cruft check` will check if your repo is up to date with the template and just give you a boolean response. ## Commit -Once you are satisfied, commit the changes to a new branch and open a PR to merge it into `main`. +Once you are satisfied, commit the changes to a new branch and open a PR to merge it into `main`. Now, check if your GitHub actions fail... 🤦🏻‍♀️ If everything is fine, you can merge the PR. 🎉 If not, you will have to fix the errors and repeat the process. 😱 diff --git a/docs/source/programming/Mount-ceph-ubuntu.md b/docs/source/programming/Mount-ceph-ubuntu.md index c5ed1fa..2a54eb2 100644 --- a/docs/source/programming/Mount-ceph-ubuntu.md +++ b/docs/source/programming/Mount-ceph-ubuntu.md @@ -9,7 +9,7 @@ The following instructions have been tested on **Ubuntu 20.04 LTS**. ## 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`. +You can do that on the terminal via `nano ~/.smb_swc`. The ``.smb_swc`` file contents should look like this: ```bash @@ -35,7 +35,7 @@ However, if someone gets access to your machine with your user logged in, they w ## 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 +```bash sudo mkdir /media/ceph-neuroinformatics ``` @@ -44,7 +44,7 @@ This will allow you to mount the storage automatically on boot. Before editing t ```bash sudo cp /etc/fstab /etc/fstab.bak ``` -Now, open the file with your favourite editor (e.g. `sudo nano /etc/fstab`) and add new lines at the end of the file. +Now, open the file with your favourite editor (e.g. `sudo nano /etc/fstab`) and add new lines at the end of the file. For example: ```bash diff --git a/docs/source/programming/SSH-vscode.md b/docs/source/programming/SSH-vscode.md index 2728fd4..599844c 100644 --- a/docs/source/programming/SSH-vscode.md +++ b/docs/source/programming/SSH-vscode.md @@ -28,4 +28,4 @@ cd .ssh/ touch config ``` -Connect to VPN, then use the `Open a remote window` (Remote - SSH extension) tool of vscode and connect to `remote-host`. You will be asked for your SWC and Linux passwords. \ No newline at end of file +Connect to VPN, then use the `Open a remote window` (Remote - SSH extension) tool of vscode and connect to `remote-host`. You will be asked for your SWC and Linux passwords. diff --git a/docs/source/programming/Troubleshooting.md b/docs/source/programming/Troubleshooting.md index 1a3d984..bf99757 100644 --- a/docs/source/programming/Troubleshooting.md +++ b/docs/source/programming/Troubleshooting.md @@ -3,15 +3,15 @@ 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. +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 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. +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 +Follow the instructions and wait for the response. diff --git a/docs/source/programming/index.md b/docs/source/programming/index.md index 96d2ab3..6572c50 100644 --- a/docs/source/programming/index.md +++ b/docs/source/programming/index.md @@ -11,4 +11,4 @@ SSH-vscode Mount-ceph-ubuntu Cookiecutter-cruft Troubleshooting -``` \ No newline at end of file +```