refactor docs (#22)

- renamed "doing things" to "Using the DNP system" - split the existing file into three sections - added a toc-tree for the index file - update the README to explain how to re-generate docs after refactor
DouglasNeuroInformatics · Aug 4, 2021 · 85eaa90 · 85eaa90
1 parent 9c3276b
commit 85eaa90
Show file tree

Hide file tree

Showing 6 changed files with 103 additions and 78 deletions.
diff --git a/README.md b/README.md
@@ -12,12 +12,23 @@ Follow these steps.
 3. open `docs/_build/index.html`
 
 To make changes, edit the markdown files.
+If you have done a major refactor (renaming files or directory structures), 
+you can use `make clean html` to create a fresh build directory for local testing.
 
 Also check out
 
 - [MyST docs](https://myst-parser.readthedocs.io/en/latest/)
 - [SPHINX docs](https://www.sphinx-doc.org/en/master/usage/quickstart.html)
 
+## Contributing
+
+If you want to contribute your expertise to this documentation,
+the best place to start would be to 
+[create a new issue](https://github.com/DouglasNeuroInformatics/Douglas_User_Documentation/issues)
+and describe the content you plan on adding. 
+This will allow other contributors to discuss with you 
+and is a good way to check if someone else is already working on a similar idea that you can collaborate on.
+
 ## Contributors ✨
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

diff --git a/docs/index.md b/docs/index.md
@@ -9,4 +9,5 @@ caption: Things we know about
 ---
 about_the_platform/index.md
 getting_started/index.md
-doing_things/index.md
+using_the_system/index.md
+
diff --git a/docs/using_the_system/access_to_data.md b/docs/using_the_system/access_to_data.md
@@ -0,0 +1,41 @@
+# Access to Data
+
+## Transferring Data
+
+Access to filesystems is enabled via the `scp/sftp` functionality of `ssh`, as
+well as the `rsync` program over `ssh`. For data transfers, please connect
+directly to `cicss03` to bypass any round-trip data would need to travel if
+performing transfers to workstations. Linux and OSX users can find the `sftp`
+`scp` and `rsync` commands in their terminal. Windows users can use
+[WinSCP](https://winscp.net/) or [FileZilla](https://filezilla-project.org/)
+for a graphical tool to access data.
+
+```{admonition} Real time data access
+The [sshfs](https://github.com/libfuse/sshfs) project allows for filesystems to be mounted remotely via ssh. See the site for details and for windows see [here](https://github.com/billziss-gh/sshfs-win).
+
+```
+
+## Accessing Human MRI Scanner DICOMS
+
+The Siemens MAGNETOM Prisma Human MRI scanner sends collected data to `cicus03`
+which acts a pseudo-PACS system, collecting the files and storing them at
+`/home/cic/dicom/transfers` accessible for 14 calendar days before being moved
+to long-term cold storage. Users are expected to access their data during that
+time and copy it to appropriate long term storage. Recovery from cold storage
+is available with delayed access and a recovery fee associated with staff time.
+
+
+## Accessing Animal MRI Scanner Raw Data
+
+The Bruker BioSpec 70/30 scanner produces data in the raw Bruker data format. 
+The data sets are accessible on the Bruker controlling computer for 14 calendar
+days from the date of the acquisition at `/opt/<PV version>/data/<username>`, 
+with `<PV version>` the ParaVision software version (PV5.1 or PV6.0.1) and `<username>` 
+the login of the user performing the scans. Users are expected to access their data 
+during that time and copy it to appropriate long term storage. Recovery is available 
+with delayed access and a recovery fee associated with staff time. Data can be accessed
+by 1) accessing the {ref}`Neuroinformatics Platform<doing_things/index:accessing the system>` and then 2) 
+accessing the bruker7t computer. The {ref}`tools for data transfer<doing_things/index:transferring data>` will 
+work, provided you take into account you need to connect to an additional computer (the bruker7t).
+
+Conversion to other formats (DICOM and NIFTI) is available upon request.
diff --git a/docs/doing_things/index.md → docs/using_the_system/access_to_software.md b/docs/doing_things/index.md → docs/using_the_system/access_to_software.md
@@ -1,77 +1,4 @@
-# Doing Things
-
-## Accessing the System
-
-The platform can be accessed in a number of ways:
-
-1. Physical access
-2. Remote access within the Douglas.
-3. Remote access outside the Douglas.
-
-### Physical Access
-
-Physical access to a suite of workstations is available inside the Douglas CIC,
-contact the CIC Administrative Assistant (Louis Théroux) for keycard access.
-
-### Remote Access within the Douglas
-
-All platform hardware is acccessible within the Douglas Research Center network
-via `ssh`. The main userserver is available at `cicus03`, the storage server
-at `cicss03` and workstations are available in the range `cicws[01..41]`.
-
-```{admonition} Playing nice
-Neuroinformatics workstations all allow for multiple simultaneous users, please
-make a best effort to choose a workstation not already being used by others.
-
-The command `who` can list currently logged-in users, while `htop` will show
-a graphical display of the current state of CPU and Memory utilization.
-```
-
-### Remote Access outside the Douglas
-
-Remote access from outside the Douglas is provided by authorization only.
-Please contact the platform to request access.
-
-## Transferring Data
-
-Access to filesystems is enabled via the `scp/sftp` functionality of `ssh`, as
-well as the `rsync` program over `ssh`. For data transfers, please connect
-directly to `cicss03` to bypass any round-trip data would need to travel if
-performing transfers to workstations. Linux and OSX users can find the `sftp`
-`scp` and `rsync` commands in their terminal. Windows users can use
-[WinSCP](https://winscp.net/) or [FileZilla](https://filezilla-project.org/)
-for a graphical tool to access data.
-
-```{admonition} Real time data access
-The [sshfs](https://github.com/libfuse/sshfs) project allows for filesystems to be mounted remotely via ssh. See the site for details and for windows see [here](https://github.com/billziss-gh/sshfs-win).
-
-```
-
-## Accessing Human MRI Scanner DICOMS
-
-The Siemens MAGNETOM Prisma Human MRI scanner sends collected data to `cicus03`
-which acts a pseudo-PACS system, collecting the files and storing them at
-`/home/cic/dicom/transfers` accessible for 14 calendar days before being moved
-to long-term cold storage. Users are expected to access their data during that
-time and copy it to appropriate long term storage. Recovery from cold storage
-is available with delayed access and a recovery fee associated with staff time.
-
-
-## Accessing Animal MRI Scanner Raw Data
-
-The Bruker BioSpec 70/30 scanner produces data in the raw Bruker data format. 
-The data sets are accessible on the Bruker controlling computer for 14 calendar
-days from the date of the acquisition at `/opt/<PV version>/data/<username>`, 
-with `<PV version>` the ParaVision software version (PV5.1 or PV6.0.1) and `<username>` 
-the login of the user performing the scans. Users are expected to access their data 
-during that time and copy it to appropriate long term storage. Recovery is available 
-with delayed access and a recovery fee associated with staff time. Data can be accessed
-by 1) accessing the {ref}`Neuroinformatics Platform<doing_things/index:accessing the system>` and then 2) 
-accessing the bruker7t computer. The {ref}`tools for data transfer<doing_things/index:transferring data>` will 
-work, provided you take into account you need to connect to an additional computer (the bruker7t).
-
-Conversion to other formats (DICOM and NIFTI) is available upon request.
-
+# Access to Software
 
 ## Accessing Scientific Software (quarantine aka modules)
 
@@ -184,6 +111,4 @@ $ module load pyminc
 pyminc/0.51(7):ERROR:151: Module 'pyminc/0.51' depends on one of the module(s) 'anaconda/miniconda3 anaconda/5.1.0-python3 anaconda/5.0.1-python3 anaconda/4.3.0-python2.7 anaconda/4.2.0-python3 anaconda/4.1.1 anaconda/2019.03-python3 anaconda/2.5 anaconda/2.3 anaconda/2.1.0 anaconda/2.0.1'
 pyminc/0.51(7):ERROR:102: Tcl command execution failed: prereq anaconda
 
-```
-
-```
+```
diff --git a/docs/using_the_system/access_to_system.md b/docs/using_the_system/access_to_system.md
@@ -0,0 +1,31 @@
+## Accessing the System
+
+The platform can be accessed in a number of ways:
+
+1. Physical access
+2. Remote access within the Douglas.
+3. Remote access outside the Douglas.
+
+### Physical Access
+
+Physical access to a suite of workstations is available inside the Douglas CIC,
+contact the CIC Administrative Assistant (Louis Théroux) for keycard access.
+
+### Remote Access within the Douglas
+
+All platform hardware is acccessible within the Douglas Research Center network
+via `ssh`. The main userserver is available at `cicus03`, the storage server
+at `cicss03` and workstations are available in the range `cicws[01..41]`.
+
+```{admonition} Playing nice
+Neuroinformatics workstations all allow for multiple simultaneous users, please
+make a best effort to choose a workstation not already being used by others.
+
+The command `who` can list currently logged-in users, while `htop` will show
+a graphical display of the current state of CPU and Memory utilization.
+```
+
+### Remote Access outside the Douglas
+
+Remote access from outside the Douglas is provided by authorization only.
+Please contact the platform to request access.
diff --git a/docs/using_the_system/index.md b/docs/using_the_system/index.md
@@ -0,0 +1,16 @@
+# Using the DNP system
+
+```{admonition} Make sure you have received your access information
+:class: warning
+
+In order to access and use the Douglas Neuroinformatics Platform,
+first ensure that you have completed the [Getting Started](../getting_started/index.md) section.
+```
+
+```{toctree}
+---
+maxdepth: 1
+---
+access_to_system.md
+access_to_data.md
+access_to_software.md