Merge branch 'docs' into 'master'

Auto-build docs from markdown files

See merge request !102

.gitignore

@@ -31,3 +31,7 @@ configure
 libtool
 Makefile
 Makefile.in
+
+# docs stuff
+doc/_build
+doc/index.rst

.gitlab-ci.yml

@@ -11,6 +11,7 @@ stages:
   - build
   - test
   - docker
+  - deploy
 
 build-env:
   stage: build
@@ -112,4 +113,37 @@ docker:tags:
     - docker build --pull -t $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG --file Dockerfile .
     - docker run -u $(id -u):$(id -g) $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG "/opt/lscsoft/bayeswave/test/test-bayeswave.sh"
     - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
-     
+
+docs:
+  stage: build
+  image: python:3.7-slim-stretch
+  variables:
+    PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+  before_script:
+    # install pandoc >= 2.0.0
+    - apt-get -yqq update
+    - apt-get -yqq install curl
+    - curl --location --output pandoc.deb https://github.com/jgm/pandoc/releases/download/2.7.2/pandoc-2.7.2-1-amd64.deb
+    - dpkg --install pandoc.deb || { apt-get -y -f install; dpkg --install pandoc.deb; }
+    # install python dependencies
+    - python3 -m pip install -r doc/requirements.txt
+  script:
+    - bash -ex doc/build.sh
+  artifacts:
+    paths:
+      - doc/_build
+  cache:
+    paths:
+      - .cache/pip
+
+pages:
+  stage: deploy
+  dependencies:
+    - docs
+  only:
+    - tags@lscsoft/bayeswave
+  script:
+    - mv doc/_build/html public
+  artifacts:
+    paths:
+      - public

README.md

@@ -67,9 +67,9 @@ and we will strive to provide what assistance we can.
 *LSC/Virgo members*:  bayeswave@sympa.ligo.org, burst@ligo.org
 
 ## Installation and operation
- * [Minimal quick-start guide](https://git.ligo.org/lscsoft/bayeswave/blob/master/doc/QUICKSTART.md)
- * [Full Installation instructions](https://git.ligo.org/lscsoft/bayeswave/blob/master/doc/INSTALLATION.md)
- * [Running Analyses](https://git.ligo.org/lscsoft/bayeswave/blob/master/doc/RUNNING.md)
+ * [Minimal quick-start guide](https://docs.ligo.org/lscsoft/bayeswave/quickstart.html)
+ * [Full Installation instructions](https://docs.ligo.org/lscsoft/bayeswave/install.html)
+ * [Running Analyses](https://docs.ligo.org/lscsoft/bayeswave/running.html)
 
 ## Available Branches
 There are two main branches (with corresponding singularity containers) in common use:

doc/build.sh

+#!/bin/bash
+
+cd "$(dirname $(readlink -f "${BASH_SOURCE[0]}"))"
+
+# convert README to index.rst for sphinx
+pandoc --from=gfm --to=rst --output=index.rst ../README.md
+
+# add a toctree to link the other markdown files
+cat >> index.rst << EOF
+
+.. toctree::
+   :hidden:
+
+   install
+   quickstart
+   running
+   examples
+EOF
+
+# run sphinx
+python3 -m sphinx -M html . _build

doc/conf.py

+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'BayesWave'
+copyright = '2019, Neil J. Cornish, Tyson B. Littenberg'
+author = 'Neil J. Cornish, Tyson B. Littenberg'
+
+# The full version, including alpha/beta/rc tags
+release = '1.0.2'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The suffix of source filenames
+source_suffix = ['.rst', '.md']
+
+# Enable parsing of markdown files
+source_parsers = {
+   '.md': 'recommonmark.parser.CommonMarkParser',
+}
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

doc/requirements.txt

+recommonmark
+sphinx
+sphinx_rtd_theme