Merge pull request #79 from university-of-york/feature/newpages

Feature/newpages

docs/source/beginners_guide/linux_shell.rst

@@ -1,4 +1,4 @@
-Linux Shell
+Linux shell
 ===========
 
 Intro
@@ -74,10 +74,10 @@ To logout of the shell type ``logout``, ``exit`` or press ``Ctrl + d``.
     The are a number of shells available to the user. In this tutorial we will be using `Bash <https://www.gnu.org/software/bash/>`_, the most widely used Linux shell.
 
 
-Files and Directories
+Files and directories
 ---------------------
 
-Filesystem Organisation
+Filesystem organisation
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 The file system is the component of the operating system that organises data into files. These files are organised into directories.
@@ -108,7 +108,7 @@ The output of the ``pwd`` command, ``/usr/researchcomp/elecclust/abs4``, is call
 The ``cd`` command lets you change your working directory to another location in the file system. ``cd`` with no arguments places you back in your home directory. The special directory ``..`` references the directory above your current directory (known as the parent directory). The is another special direcory ``.`` which references the current directory. These two directories can be viewed as *links*.
 
 
-Listing Files and Directories
+Listing files and directories
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To list the files in a directory use the ``ls`` (list) command.
@@ -253,7 +253,7 @@ The next example displays the directory in the long format using the ``-l`` opti
 Using a directory name as an option causes ``ls`` to list the contents of the directory. To list the attributes of the directory use the ``-d`` option. You can use a pathname as the argument.
 
 
-Creating, Moving and Copying Files and Directories
+Creating, moving and copying files and directories
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 You can create directories, move or copy files or directories to other locations in the filesystem using the ``mkdir`` (make directory) ``mv`` (move) and ``cp`` (copy) commands.
@@ -343,7 +343,7 @@ To delete directories use the ``rmdir`` (remove directory) command.
 ``rmdir`` will only remove empty directories. To remove a directory and all it's contents use the ``rm -r`` (recursive) option to the ``rm`` command. To be safe and check the files before you remove them use ``rm -ri`` (recursive and interactive) options.
 
 
-Editing and Displaying the Contents of Files
+Editing and displaying the contents of files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Text Editors
@@ -410,7 +410,7 @@ The ``cat`` command displays all the text in the users file on the screen. This
    | ``/pattern``    - search for text in the file
 
 
-Files and Directory Permissions
+Files and directory permissions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Groups are provided to manage sets of users and control access to files and directories. All users belong to a default group and may be a member of other groups.
@@ -470,7 +470,7 @@ In the above example the first column of the directory listing shows the permiss
 This is a ``directory``, the owner ``abs4`` can ``read``, ``write`` and ``access`` the directory. Members of the group, ``csrv``, can ``read`` and ``access`` the directory, they can not create or ``write`` to files in the directory, all ``other`` users do not have any access to the directory.
 
 
-Changing Permissions
+Changing permissions
 """"""""""""""""""""
 
 To change file permissions use the ``chmod`` command.
@@ -547,7 +547,7 @@ To change the group of a file use the  command ``chgrp <groupname> <filename>``.
     -bash-4.1$
 
 
-History, Command Line Editing and Job Control
+History, command line editing and job control
 ---------------------------------------------
 
 History
@@ -570,7 +570,7 @@ The history command lists the last commands you typed.
     -bash-4.1$
 
 
-Command Line Editing
+Command line editing
 ^^^^^^^^^^^^^^^^^^^^
 
 You can select past commands using the ``up`` and ``down`` arrow keys. You can edit the command line using the ``left`` and ``right`` arrow keys and any of the following commands:
@@ -593,7 +593,7 @@ ESC-B	            move back one word
 ===============     =====================================
 
 
-Job Control
+Job control
 ^^^^^^^^^^^
 
 Job control deals with managing your programs whilst they are running. Linux uses the name process for a running program. The ``ps`` command list all the processes you have running.
@@ -670,16 +670,16 @@ The sleep command does nothing for the number of seconds specified in the argume
 
 In this example we put two jobs into the background. The ``fg`` command moves the last job placed in the background into the foreground. ``Ctrl-z`` *stops* (pauses, not kills) the job and returns to the command line. The ``bg`` command places the paused job in the background. ``fg`` can bring specific jobs to the foreground by specifying the job number.
 
-Environment Variables and Shell Scripts
+Environment variables and shell scripts
 ---------------------------------------
 
-Environment Variables
+Environment variables
 ^^^^^^^^^^^^^^^^^^^^^
 
 In the Linux shell a variable is a named object that contains data and which can be used by programs and commands.  Environment variables provides a simple way to share configuration settings between multiple applications and processes in Linux. For example the value of an environmental variable can be the default editor that should be used, which can then be used by command to invoke the correct editor when necessary.
 
 
-Predefined Environment Variables
+Predefined environment variables
 """"""""""""""""""""""""""""""""
 ==========  =========================================================================
 Variable    Value
@@ -710,7 +710,7 @@ To use an environment variable precede its name with a ``$`` character. We can d
     -bash-4.1$
 
 
-Shell Scripts
+Shell scripts
 ^^^^^^^^^^^^^
 
 Shell scripts are files which contain shell commands. You run the script by typing its filename. Things to note:
@@ -749,10 +749,10 @@ Shell scripts are files which contain shell commands. You run the script by typi
     -bash-4.1$
 
 
-Input and Output Redirection, Pipes, and Filters
+Input and output redirection, pipes, and filters
 ------------------------------------------------
 
-Input and Redirection
+Input and redirection
 ^^^^^^^^^^^^^^^^^^^^^
 
 We can change the behaviour of programs to redirect input from a file instead of the keyboard and write to a file instead of the screen. The ``>`` character is used to redirect output to a file and ``<`` to redirect input.
@@ -915,7 +915,7 @@ The ``last`` command displays all users and the dates and times they have logged
     -bash-4.1$
 
 
-Useful Commands
+Useful commands
 ---------------
 
 To find more information on any command below, type ``man <command>`` which will open up the built-in manual page for that command.

docs/source/conf.py

@@ -6,8 +6,8 @@
 # -- Project information
 
 project = 'Viking Documentation'
-copyright = '2023, University of York'
-author = 'University of York'
+copyright = '2023, The University of York'
+author = 'The University of York'
 
 release = '0.1'
 version = '0.1.0'

docs/source/getting_started/backing_up.rst

@@ -1,4 +1,4 @@
-Backing Up your Data
+Backing up your data
 ====================
 
 There are two main options depending on how frequently you need to access the data, the University **Filestore** or the **Vault**.
@@ -13,7 +13,7 @@ The **Filestore** is more readily accessible, if you need more space please cont
     Please ensure you **regularly** back up your data, if there is a catastrophic failure all data on Viking could be lost!
 
 
-The Vault
+The vault
 ----------
 
 Vault is a file archiving service.  It can be used to store files that need to be kept, but are unlikely to be accessed again.  The main use is for storing research data which needs to be kept for contractual or other reasons, but is probably never going to be used or looked at again. Please see the `Vault User Guide <https://support.york.ac.uk/s/article/Vault-User-Guide>`_ for more details.

docs/source/getting_started/code_of_conduct.rst

@@ -1,20 +1,20 @@
-Code of Conduct
+Code of conduct
 ===============
 
 .. FIXME: Needs suggestions
 
 We hope everyone enjoys using Viking and all its powerful resources. As all of Viking's resources are shared amongst all users, it's up to all of us to do our best to ensure we are using them wisely and not negatively impacting other users. We understand that for some people this may be the first time they have access to a HPC like Viking, or even the first time using a Linux machine, so we have created this page to provide some guidelines for using Viking responsibly and considerately. As always, if you need help with any explanation please get in touch with the team by emailing [email protected].
 
 
-Running Tasks on the Login Nodes
+Running tasks on the login nodes
 --------------------------------
 
 When you first log in to Viking you, and every other user, will be logged into one of the ``login nodes``. These act as gateways to the ``compute nodes``, which is where all the hard work should be done. The login nodes are meant for transferring files, writing code, viewing results and other similar **light work**. If you have a task which crunches through a massive data set, spinning off multiple instances and taking up as many CPUs as it can to get the job done, then running this task on a login node will negatively impact upon other people's ability to do their work.
 
 Please run all serious work through the ``slurm`` job scheduler, this way they are run on the compute nodes, not the login nodes and you can control their resources. You can read about ``Slurm`` and how to send jobs to it on the :doc:`scheduling jobs page </using_viking/submitting_jobs>`.
 
 
-Closing Virtual Desktop Sessions
+Closing virtual desktop sessions
 --------------------------------
 
 :doc:`Virtual desktop sessions <../using_viking/virtual_desktops>` don't close if you simply disconnect, this is to allow you to come back to them at a later time. If you do not ``kill`` the virtual desktop after you have finished and later create new ones, more and more virtual desktops will be running taking up resources. This is why it's required to simply :ref:`kill virtual desktops when finished with <kill_sessions>`.
@@ -26,7 +26,7 @@ Backing up data
 The ``scratch`` folder, a large area in your home directory where you can store data, is **not backed up**. This is partly due to the sheer size of the filesystem and means that backing up data is each user's responsibility. In a worst case scenario all data could be lost, therefore you should regularly :doc:`back up your data </getting_started/backing_up>`. If you need any help with this, please get in touch with [email protected].
 
 
-Deleting Unneeded Files
+Deleting unneeded files
 -----------------------
 
 We strongly encourage all users to take time to periodically sort through their data on Viking, back up the data and when it's successfully backed up, delete it from Viking if it's no longer needed. This frees up space for other people's data on the filesystem and helps avoid us reaching storage limits.

docs/source/getting_started/connecting_off_campus.rst

@@ -1,26 +1,26 @@
 .. _connecting-off-campus:
 
-Connecting to Viking off campus
+Connecting to viking off campus
 ===============================
 
-Viking has been configured to only allow connections from the university network. Therefore, in order to access Viking off-campus, you must first connect to either the VPN service, or create an ``ssh`` tunnel. These re-route your traffic through the university network allowing you to connect to Viking as if you were on campus.
+Viking has been configured to only allow connections from the University network. Therefore, in order to access Viking off-campus, you must first connect to either the VPN service, or create an ``ssh`` tunnel. These re-route your traffic through the University network allowing you to connect to Viking as if you were on campus.
 
 Using the VPN
 -------------
 
 Please see the main IT Services page on using the VPN found `here <https://www.york.ac.uk/it-services/services/vpn/>`_.
 
 
-SSH Gateway
+SSH gateway
 -----------
 
 The University also provides an `SSH gateway service <https://www.york.ac.uk/it-services/services/ssh/>`_ that can be used to allow off-campus access to Viking, as an alternative to the VPN. To use this method, ``ssh`` to ``ssh.york.ac.uk`` (substituting your username for ``abc123``):
 
 .. code-block:: console
 
-    $ ssh abc123@viking.york.ac.uk
+    $ ssh abc123@ssh.york.ac.uk
 
-Once you have entered your password and gone through the two-factor authentication, you should then see the following message asking which machine you wish to connect to. Simply enter ``viking`` and press ``Enter``.
+Once you have entered your password and gone through the 2FA (two-factor authentication), you should then see the following message asking which machine you wish to connect to. Simply enter ``viking`` and press ``Enter``.
 
 .. code-block:: console
 
@@ -41,4 +41,5 @@ To avoid manual entering the hostname when using the SSH gateway, it's also poss
     ssh -J [email protected] viking
 
 .. hint::
-    You will still need to enter your password, and complete the 2FA as before.
+
+    You will still need to enter your password, and then complete the 2FA.

docs/source/getting_started/connecting_to_viking.rst

@@ -1,4 +1,4 @@
-Connecting to Viking
+Connecting to viking
 ====================
 
 .. hint::
@@ -7,10 +7,10 @@ Connecting to Viking
 To access Viking you'll need to be on the campus network or using the VPN :doc:`which you can read about here. </getting_started/connecting_off_campus>`
 
 
-Terminal Access
+Terminal access
 ---------------
 
-Linux and MacOS
+Linux and macOS
 ^^^^^^^^^^^^^^^
 
 To log in from a terminal emulator, use the following command:
@@ -36,7 +36,7 @@ Windows
 For terminal access to Viking from a Windows desktop, you will need to install `PuTTY <https://www.chiark.greenend.org.uk/~sgtatham/putty/>`_ (or comparable software).
 
 
-Configuring PuTTY to Connect to Viking
+Configuring PuTTY to connect to viking
 """""""""""""""""""""""""""""""""""""""
 
 Open PuTTY and configure it to connect to Viking:
@@ -48,7 +48,7 @@ Open PuTTY and configure it to connect to Viking:
 
 .. image:: ../assets/img/putty1.png
 
-Connecting to Viking
+Connecting to viking
 """""""""""""""""""""
 
 1. Start PuTTY
@@ -57,7 +57,7 @@ Connecting to Viking
 
 .. image:: ../assets/img/putty2.png
 
-A terminal window should appear. Log in with your university username and password.
+A terminal window should appear. Log in with your University username and password.
 
 .. image:: ../assets/img/putty3.png
 

docs/source/getting_started/creating_accounts.rst

@@ -1,6 +1,6 @@
 .. _creating-an-account:
 
-Creating an Account
+Creating an account
 ===================
 
 Getting access to Viking is a simple two-stage process:
@@ -9,7 +9,7 @@ Getting access to Viking is a simple two-stage process:
 2. Members can then use this ``project code`` to complete the `user application form <https://docs.google.com/forms/d/e/1FAIpQLSfXkL10ypU6EQCBB2jS5oDwTpRMo77ppl7dvdbLnXm5zrKR7Q/viewform>`_. The PI will be notified each time a user account is assigned to the project.
 
 
-Project Application
+Project application
 -------------------
 In order to use Viking, the project PI (or supervisor) must apply for a Viking project account. These will be used to monitor the usage of Viking, and attribute usage by researchers across the University. We ask that the PI who applies for the account is a permanent member of staff, as this will allow us to have a permanent contact for project reporting purposes. You may also nominate a deputy, who can deal with any project enquiries on your behalf. A PI may request more than one project code, such as in the situation when they have multiple projects.
 
@@ -21,7 +21,7 @@ Once the application has been approved, a new Viking project code will be suppli
 
 `The Project Application Form can be found here <https://docs.google.com/forms/d/e/1FAIpQLSdyldpc8nBtbsFaY5BDLHo9542-A1Y7segJ7d4Fwjl2yj7mxw/viewform>`_.
 
-User Account Application
+User account application
 ------------------------
 Each user on Viking must apply for an individual user account that will be associated with at least one project group. In order to complete the user account application form, **you must already have a valid project code**. If you are unsure what your project code is, you should contact your PI (or supervisor) who should be able to supply you with a suitable project code or request a new one by completing the project application form.