Merge pull request #939 from Youssef15015/docs_deployment

Deploying documentation using Azure

azure-pipelines/doc-build.yml

@@ -0,0 +1,70 @@
+# Specify which branches you want to trigger for continuous deployment and/or applicable for pull requests.
+# Otherwise it triggers all of them.
+trigger:
+- master
+
+pr:
+- master
+
+# Variables we can reference later.
+variables:
+  system.debug: 'true'
+  tardis.build.dir: $(Build.Repository.LocalPath)
+
+
+jobs:
+# Title of job
+# Virtual machine selected from the available pools.
+- job: 'Build_Documentation'
+  pool:
+    vmImage: 'Ubuntu-16.04'
+
+  steps:
+# When setting up the azure pipeline for the first time, generate a ssh key locally
+# and add the generated public key to github as a deploy key through forked_repo_home/settings/deploy_key.
+# Use steps listed from: https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys.
+
+# Secure files stored in the azure server are encryped and again decrypted by the azure task that uses the file.
+# Download a secure file to a temporary location in the virtual machine.
+  - task: DownloadSecureFile@1
+    inputs: 
+      secureFile: 'id_azure_rsa'
+# Make sure you've added the generated private key file (named 'id_azure_rsa' here) to library & authorize it for all pipelines.
+# by using: https://docs.microsoft.com/en-us/azure/devops/pipelines/library/secure-files?view=azure-devops#how-do-i-authorize-a-secure-file-for-use-in-all-pipelines.
+
+# Install an SSH key prior to a build or release.
+# This is needed to give azure access to deploy to github.
+# hostName is the line that was added to ~/.ssh/known_hosts when you added the RSA host key. (Output of ssh-keyscan should look something like: [1]As3..=ssh-rsa ..).
+# sshPublicKey should be a string value of what is inside your .pub file (i.e: rsa-key Axddd... username@server).
+# sshKeySecureFile is the downloaded secure file you generated.
+  - task: InstallSSHKey@0
+    inputs:
+     hostName: $(gh_host)
+     sshPublicKey: $(public_key)
+     #sshPassphrase: $(Agent.TempDirectory)  # Optional - leave empty if it was left empty while generating the key.
+     sshKeySecureFile: 'id_azure_rsa'
+# For more details, see: http://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/install-ssh-key?view=azure-devops#example-setup-using-github.
+# You can mask hostName & sshPublicKey values under secret variables (i.e. gh_host & public_key here) in your azure pipeline build page.
+# Follow these steps: https://docs.microsoft.com/en-us/azure/devops/pipelines/process/variables?view=azure-devops&tabs=yaml%2Cbatch#secret-variables.
+
+# ##vso[task.prependpath] is a built-in logging command to add paths.
+# Add conda to the list of paths available from the terminal.
+  - bash: |
+          echo "##vso[task.prependpath]$CONDA/bin"        
+    displayName: Add conda to PATH
+# Make the vm user the owner of the conda path.
+# Update conda without asking for confirmation.
+  - bash: |
+      sudo chown -R $USER $CONDA
+      conda update -y conda    
+    displayName: updating conda and activating
+# Install the conda environment made for tardis.
+  - bash: |
+        sh ci-helpers/install_tardis_env.sh     
+    displayName: 'Install TARDIS env'
+# Activate the environment, use sphinx to make the html documentation of the build, and deploy to gh-pages.
+  - bash: |
+        source activate tardis
+        bash deploy_docs.sh
+    displayName: 'TARDIS build and deployment to gh-pages'
+# See github.com/tardis-sn/tardis for the contents of these files.

deploy_docs.sh

@@ -0,0 +1,59 @@
+# Modified from https://github.com/AMReX-Codes/amrex/blob/master/build_and_deploy.sh
+# and licensed according to BSD-3-Clause-LBNL (https://github.com/AMReX-Codes/amrex/blob/master/LICENSE).
+
+#!/bin/bash
+set -e # Exit with nonzero exit code if anything fails
+
+# Build the documentation from the SOURCE_BRANCH
+# and push it to TARGET_BRANCH.
+SOURCE_BRANCH="master"
+TARGET_BRANCH="gh-pages"
+
+# Save some useful information
+REPO=`git config remote.origin.url`
+SSH_REPO=${REPO/https:\/\/github.com\//git@github.com:}
+SHA=`git rev-parse --verify HEAD`
+
+# Clone the existing gh-pages for this repo into out/
+git clone $REPO out
+cd out
+
+# Create a new empty branch if gh-pages doesn't exist yet (should only happen on first deploy)
+git checkout $TARGET_BRANCH || git checkout --orphan $TARGET_BRANCH
+
+# Clean out existing contents
+git rm -rf . || exit 0
+cd ..
+
+# Pull from SOURCE_BRANCH again
+git pull $SSH_REPO $SOURCE_BRANCH
+
+# Build the Sphinx documentation
+cd docs
+make html
+cd ../  
+
+# Move it to the gh-pages branch
+mv -f docs/_build/html/* out/
+touch out/.nojekyll
+
+# Now let's go have some fun with the cloned repo
+cd out
+git config --local user.name "Azure Pipelines"
+git config --local user.email "[email protected]"
+
+echo "doing git add/commit/push"
+
+# Commit the "changes", i.e. the new version.
+# The delta will show diffs between new and old versions.
+git add --all
+
+# Exit if there are no docs changes
+if git diff --staged --quiet; then
+   echo "exiting with no docs changes"
+   exit 0
+fi
+
+# Otherwise, commit and push
+git commit -m "Deploy to GitHub Pages: ${SHA}"
+git push $SSH_REPO $TARGET_BRANCH

docs/workflow/azure_links.inc

@@ -0,0 +1,15 @@
+
+.. azure stuff
+.. _Azure Devops: http://azure.microsoft.com/en-us/services/devops/?nav=mi
+.. _Azure ssh-task: http://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/utility/install-ssh-key?view=azure-devops#example-setup-using-github
+.. _Azure secure files: http://docs.microsoft.com/en-us/azure/devops/pipelines/library/secure-files?view=azure-devops#how-do-i-authorize-a-secure-file-for-use-in-all-pipelines
+.. _Azure variables: http://docs.microsoft.com/en-us/azure/devops/pipelines/process/variables?view=azure-devops&tabs=yaml%2Cbatch#secret-variables
+.. _Azure secure files: http://docs.microsoft.com/en-us/azure/devops/pipelines/library/secure-files?view=azure-devops#how-do-i-authorize-a-secure-file-for-use-in-all-pipelines
+.. _Azure task: http://github.com/microsoft/azure-pipelines-tasks
+
+.. general stuff
+.. _Continuous Integration: https://en.wikipedia.org/wiki/Continuous_integration
+
+.. |emdash| unicode:: U+02014
+
+.. vim: ft=rstS