Merge remote-tracking branch 'upstream/master' into docs/clean_up

docs/development/azure_links.inc

@@ -8,6 +8,8 @@
 .. _azure task: http://github.com/microsoft/azure-pipelines-tasks
 .. _azure pipelines agent releases: https://github.com/Microsoft/azure-pipelines-agent/releases
 .. _azure self hosted agents: https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/agents?view=azure-devops#install
+.. _azure tutorial: https://docs.microsoft.com/en-us/azure/devops/pipelines/create-first-pipeline?view=azure-devops&tabs=tfs-2018-2
+.. _azure condition statements: https://docs.microsoft.com/en-us/azure/devops/pipelines/process/conditions?view=azure-devops&tabs=yaml
 .. _personal access token PAT: https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops
 .. _self agent services: https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/v2-linux?view=azure-devops#run-as-a-systemd-service
 .. _agent pool security roles: https://docs.microsoft.com/en-us/azure/devops/organizations/security/about-security-roles?view=azure-devops#agent-pool-security-roles-project-level

docs/development/continuous_integration.rst

@@ -75,23 +75,37 @@ For explicit details, see `git deploy key`_.
 Adding your key locally and copying the known host name
 -------------------------------------------------------
 
-If you wish to deploy the documentation locally to gh-pages, you must add the generated key on your computer::
+**Instead of the method recommended by azure, you can add all the github hosts by copying this output, starting from: github.com ssh-rs...**
+[Default option suggested by wk]::
+
+    ssh-keyscan -t rsa github.com
+
+If you wish to deploy the documentation locally to gh-pages, you must add the generated key on your computer and clone your repository::
 
     $ eval "$(ssh-agent -s)"
     $ ssh-add ~/.ssh/id_rsa (Or whatever you called your key)
     $ ssh-agent -k
+    $ git clone [email protected]:myOrganizationName/myRepositoryName.git
+    
 
-Copy the saved known host, as we will need it for installing the key on Azure.
-It should look something like (should look something like [1]As3..=ssh-rsa ..) and will be the last line added to::
+Accept the warning to add github and copy the saved known host, as we will need it for installing the key on Azure.
+It should look something like (should look something like [1]As3...=ssh-rsa ..) and will be the last line added to::
 
      ~/.ssh/known_hosts 
 
+It is generally advisable to leave a comment at the end of your added known host line to be able to identify it later, by simply inputting it at the end
+of the known host, such as: ([1]As3...=ssh-rsa AAA.. comment). If you already have it added from before, the portion after ssh-rsa should always start with AAAAB3NzaC1yc2EAAAABIwAAAQ...
 
 Setting up Azure services 
 =========================
 
 The first step is to visit `Azure Devops`_ and create an account.
 
+Adding a pipeline on Azure Devops
+---------------------------------
+
+Follow this `Azure tutorial`_ to generate your first test pipeline. This shows you how to add a YAML file for your pipeline.
+
 Adding the key to Azure's secure files
 --------------------------------------
 
@@ -122,6 +136,8 @@ and/or applicable for pull requests. Otherwise, it triggers all of them::
     pr:
     - branch_name
 
+**Alternatively, you can input:- none, to not trigger anything.**
+
 It follows the following hierarchy:
 
 Pipeline hierarchy
@@ -156,7 +172,7 @@ Download a secure file to a temporary location in the virtual machine::
 
       - task: InstallSSHKey@0
         inputs:
-          hostName: $(gh_host)
+          knownHostsEntry: $(gh_host)
           sshPublicKey: $(public_key)
           #sshPassphrase: # Optional - leave empty if it was left empty while generating the key.
           sshKeySecureFile: 'id_azure_rsa'
@@ -180,7 +196,7 @@ selecting the three dots on the top right while editing that pipeline, as seen h
 
   .. image:: images/variables.png
 
-After defining the variable, one can encrypt it using this lock symbol:
+After defining the variable, one could optionally encrypt it using this lock symbol:
 
   .. image:: images/lock.png
 
@@ -199,7 +215,8 @@ If you are using a self hosted agent (see `Installing and running a self hosted
       pool:
         name: "agent_pool_name"
 
-Or if you prefer to use multiple virtual machines and specity the maximum that can run at the same time::
+Or if you prefer to use multiple virtual machines and specity the maximum that can run at the same time, in 
+addition to specifying variables as key value pairs such as conda and miniconda.url below ::
 
       strategy:
         matrix: 
@@ -209,7 +226,12 @@ Or if you prefer to use multiple virtual machines and specity the maximum that c
           mac:
             vm_Image: 'macOS-10.13'
             miniconda.url: 'http://repo.continuum.io/miniconda/Miniconda2-latest-mac-x86_64.sh'
-        maxParallel: 4
+        maxParallel: 2
+      pool:
+        vmImage: $(imageName)
+
+This trick is also convenient for specying different variable builds for the same vmImage. As one can keep the vm_Image 
+constant, and change the key value pair for each job in the matrix.
 
 Installing and running a self hosted agent
 ------------------------------------------
@@ -271,6 +293,19 @@ see `self agent services`_
 
 For more details, see `Azure self hosted agents`_ 
 
+Carsus
+------
+
+"Carsus is a TARDIS support package for creating and working with atomic datasets" (Carsus_)
+
+Azure services are also set up on Carsus for automatic debugging. In addition to everything mentioned, the pipelines for
+Carsus also use `Azure condition statements`_, for activating a job, step, or stage upon a specific environment or case. 
+
+Debugging
+---------
+
+Sometimes inputs are required using single citation marks '' instead of double ones "", and alternatively no citation marks at all.
+
 Additional references
 --------------------
 

docs/development/git_links.inc

@@ -56,6 +56,7 @@
 .. _ipython git workflow: http://mail.scipy.org/pipermail/ipython-dev/2010-October/006746.html
 .. other stuff
 .. _python: http://www.python.org
+.. _carsus: https://tardis-sn.github.io/carsus/
 
 .. |emdash| unicode:: U+02014