Add documentation publishing automation (#348)

* Add documentation publishing automation

This commit adds a github actions CI job that will run on each merged
commit that will trigger a documentation build and publish the contents
to https://qiskit.org/documentation/metal when the repo is made public
and CI can be run.

* restored makefile to output to _build instead of build

.github/workflows/docs.yml

@@ -0,0 +1,29 @@
+---
+name: Docs Publish
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.7'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -U virtualenv setuptools wheel tox
+        sudo apt-get install graphviz pandoc qt5-default
+    - name: Build and publish
+      env:
+        encrypted_rclone_key: ${{ secrets.encrypted_rclone_key }}
+        encrypted_rclone_iv: ${{ secrets.encrypted_rclone_iv }}
+        QISKIT_DOCS_BUILD_TUTORIALS: 'always'
+      run: |
+        tools/deploy_documentation.sh

docs/Makefile

@@ -14,7 +14,7 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = .
-BUILDDIR      = build
+BUILDDIR      = _build
 RELEASEDIR    = published
 
 # Put it first so that "make" without argument is like "make help".

docs/build_docs.py

@@ -108,4 +108,13 @@
 
 os.chdir(pwd)
 
+# for local build, copy from _build to build directory
+print("Copying locally to build directory\n")
+import shutil
+original = Path(pwd, 'docs', '_build')
+destination = Path(pwd, 'docs', 'build')
+if os.path.exists(destination):
+    shutil.rmtree(destination)
+shutil.copytree(original, destination)
+
 print("Build Complete!")

docs/make.bat

@@ -8,7 +8,7 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR= .
-set BUILDDIR= build
+set BUILDDIR= _build
 
 if "%1" == "" goto help
 

qiskit_metal/__init__.py

@@ -76,7 +76,7 @@ def set_attribute(name: str, value=True):
             # AA_DontUseNativeMenuBar
             # AA_MacDontSwapCtrlAndMeta
 
-    if 1:
+    if not os.getenv('QISKIT_METAL_HEADLESS', None):
         import matplotlib as mpl
         mpl.use("Qt5Agg")
         import matplotlib.pyplot as plt

requirements-dev.txt

@@ -14,4 +14,6 @@ sphinx
 numpydoc
 sphinx-automodapi
 jupyter_sphinx
-qiskit-sphinx-theme
+nbsphinx
+qiskit-sphinx-theme
+jupyter_nbgallery

tools/deploy_documentation.sh

@@ -0,0 +1,33 @@
+
+#!/bin/bash
+
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2018, 2019.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+# Script for pushing the documentation to the qiskit.org repository.
+set -e
+
+curl https://downloads.rclone.org/rclone-current-linux-amd64.deb -o rclone.deb
+sudo apt-get install -y ./rclone.deb
+
+RCLONE_CONFIG_PATH=$(rclone config file | tail -1)
+
+# Build the documentation.
+tox -edocs -- -j auto
+
+echo "show current dir: "
+pwd
+
+# Push to qiskit.org website
+openssl aes-256-cbc -K $encrypted_rclone_key -iv $encrypted_rclone_iv -in tools/rclone.conf.enc -out $RCLONE_CONFIG_PATH -d
+echo "Pushing built docs to website"
+rclone sync --progress ./docs/_build/html IBMCOS:qiskit-org-web-resources/documentation/metal

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 minversion = 2.1
-envlist = py35, py36, py37, py38, lint, docs
+envlist = py37, lint, docs
 skipsdist = True
 
 [testenv]
@@ -15,6 +15,7 @@ commands =
   python -m unittest -v
 
 [testenv:lint]
+basepython = python3.7
 deps =
   pycodestyle
   pylint
@@ -25,24 +26,24 @@ commands =
   pylint -rn --rcfile={toxinidir}/.pylintrc test
   doc8 docs
 
-[testenv:asv]
-deps =
-  asv
-  virtualenv
-commands =
-  asv run {posargs}
-
 [testenv:docs]
+basepython = python3.7
 envdir = .tox/docs
 passenv = DOCS_FROM_MASTER QISKIT_DOCS_BUILD_TUTORIALS
+setenv =
+    {[testenv]setenv}
+    QISKIT_METAL_HEADLESS=1
 deps =
   -r requirements-dev.txt
-  sphinx-intl
 commands =
   sphinx-build -b html {posargs} {toxinidir}/docs/ {toxinidir}/docs/_build/html
 
 [testenv:gettext]
+basepython = python3.7
 envdir = .tox/docs
+setenv =
+    {[testenv]setenv}
+    QISKIT_METAL_HEADLESS=1
 deps =
   -r requirements-dev.txt
   sphinx-intl