documentation build scripts

.gitignore

@@ -9,11 +9,12 @@ MANIFEST
 *.egg-info
 .eggs
 
-# built stuffs
-build/
+# build stuffs
+doc/*
+!doc/joss-paper
 
 # derived files
-doc/src/appendices/command-ref.rst
+src/appendices/command-ref.rst
 
 # editor stuff
 *.swp

.travis.yml

@@ -27,26 +27,17 @@
 ---
 cache: pip
 dist: xenial
-addons:
-  apt:
-    update: true  # instruct travis-ci to always run apt-get before each build
 
 language: python
-
-stages:
-- documentation
+python:
+  - "3.7"
 
 env:
   global:
     - PATH="${TRAVIS_BUILD_DIR}/bin:$PATH"
 
-jobs:
-  include:
+install:
+  - pip install -e .
 
-  # build documentation
-  - stage: documentation
-    python: "3.7"
-    install:
-      - .travis/install.sh docs
-    script:
-      - python setup.py build_sphinx
+script:
+  - make html singlehtml linkcheck SPHINXOPTS='-W'

Makefile

@@ -0,0 +1,36 @@
+# Minimal makefile for Sphinx documentation
+
+# You can set these variables from the command line:
+# e.g. $ make html CYLC_VERSION=1.2.3
+CYLC_VERSION = $(shell cylc version)
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+SOURCEDIR = src
+BUILDDIR = doc/$(CYLC_VERSION)
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+cleanall:
+	(cd doc; echo [0-9]*.*)
+	rm -rI doc/[0-9]*.*
+
+cli:
+	# auto-document CLI reference
+	bin/autodoc-cli
+
+.PHONY: help clean cli Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile cli
+	# build documentation
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	# write out dict of availabe versions and formats
+	bin/write-version-file doc/versions.json
+	# setup HTML redirects to point at this version
+	bin/set-default-path "$(CYLC_VERSION)" html

README.md

@@ -1,12 +1,21 @@
-# cylc-doc
+# Cylc Documentation
 
-Documentation (User Guide, Cheat Sheets, etc.) for the Cylc Workflow Engine.
+[![Build Status](https://travis-ci.org/cylc/cylc-doc.svg?branch=master)](https://travis-ci.org/cylc/cylc-doc)
+
+Documentation for the Cylc Workflow Engine and its software ecosystem.
 
 ## Development
 
 ```console
 $ git clone [email protected]:cylc/cylc-doc.git cylc-doc
 $ cd cylc-doc
 $ pip install -e .
-$ python setup.py build_sphinx
+$ make html
+```
+
+## Testing
+
+```console
+# note: -W tells Sphinx to fail on warnings
+$ make html linkcheck doctest SPHINXOPTS='-W'
 ```

_config.yml

@@ -0,0 +1,15 @@
+# This file configures the Jekyll static web builder (https://jekyllrb.com/) as
+# used by Github Pages.
+
+# Jekyll treats directories beginning with underscores as having special meaning
+# and omits them from the build. This can be overridden by manually including
+# directories using "include".
+# https://help.github.com/articles/files-that-start-with-an-underscore-are-missing/
+# NOTE: Only the directory name should be specified not the full path.
+include: [
+    "_downloads",
+    "_images",
+    "_modules",
+    "_sources",
+    "_static"
+]

src/custom/make-commands.sh → bin/autodoc-cli

@@ -1,5 +1,4 @@
 #!/bin/bash
-
 # THIS FILE IS PART OF THE CYLC SUITE ENGINE.
 # Copyright (C) 2008-2019 NIWA & British Crown (Met Office) & Contributors.
 # 
@@ -19,7 +18,7 @@
 # Create appendices/command-ref.rst for inclusion in HTML doc.
 
 # All paths relative to 'doc/src/custom/' directory:
-COMMAND_REF_FILE="$(dirname "$0")/../appendices/command-ref.rst"
+COMMAND_REF_FILE="$(dirname "$0")/../src/appendices/command-ref.rst"
 CYLC="cylc"
 
 cat > "$COMMAND_REF_FILE" <<END