Document generation and fixes default run sg

Dockerfile

@@ -6,6 +6,8 @@
 #
 
 # dockerfile to spin up a container suitable for generation of documentation
+# - Gem/pip files used for setup are located in /usr/local/src
+# - The default build_docs.sh is in /usr/local/src/scripts
 
 FROM centos:7
 LABEL maintainer="toolkit@shotgunsoftware.com"
@@ -18,58 +20,66 @@ LABEL maintainer="toolkit@shotgunsoftware.com"
 RUN yum update -y && \
     yum install -y epel-release && \
     yum install -y \
-    # Generic build packages
-    autoconf \
-    automake \
-    gcc \
-    gcc-c++ \
-    git \
-    libtool \
-    make \
-    nasm \
-    perl-devel \
-    zlib-devel \
-    tar \
-    nc \
-    xz \
-    # sphinx
-    pandoc \
-    # Python libs
-    python-pip \
-    # Ruby
-    libyaml-devel \
-    openssl-devel \
-    libreadline-dev \
-    zlib-devel \
-    python-pyside \
+        # Generic build packages
+        # autoconf, automake, gcc will be installed as libtool dependencies
+        gcc-c++ \
+        git \
+        libtool \
+        make \
+        nasm \
+        nc \
+        perl-devel \
+        # sphinx
+        pandoc \
+        # Python libs
+        python-pip \
+        python-pyside \
+        # Ruby
+        libreadline-dev \
+        libyaml-devel \
+        openssl-devel \
+        zlib-devel && \
     yum clean all
 
 # Ruby
 ENV RUBY_MAJOR_VER=2.5 \
-    RUBY_VER=2.5.3 \
-    PATH=/opt/ruby-2.5/bin:$PATH
+    RUBY_VER=2.5.3
+ENV PATH=/opt/ruby-${RUBY_MAJOR_VER}/bin:$PATH
 RUN DIR=$(mktemp -d) && cd ${DIR} && \
-    curl -OLs http://ftp.ruby-lang.org/pub/ruby/ruby-$RUBY_VER.tar.gz  && \
-    tar xzf ruby-$RUBY_VER.tar.gz && \
-    cd ruby-$RUBY_VER && \
-    ./configure --prefix=/opt/ruby-${RUBY_VER} --bindir=/opt/ruby-${RUBY_VER}/bin --disable-install-doc && \
-    make -j 8 && \
+    curl -Ls http://ftp.ruby-lang.org/pub/ruby/ruby-${RUBY_VER}.tar.gz | \
+        tar --strip-components=1 -xz && \
+    ./configure \
+        --prefix=/opt/ruby-${RUBY_VER} \
+        --bindir=/opt/ruby-${RUBY_VER}/bin \
+        --disable-install-doc && \
+    make -j $(nproc) && \
     make install && \
     make distclean && \
     rm -rf ${DIR} && \
     cd /opt/ && ln -sfn ruby-${RUBY_VER} ruby-${RUBY_MAJOR_VER}
 
-RUN mkdir -p /app
-WORKDIR /app
-
-COPY ./Gemfile /app
-COPY ./Gemfile.lock /app
-COPY ./requirements.txt /app
+# Copy in any Gem/pip related files
+WORKDIR /usr/local/src
+COPY ./Gemfile .
+COPY ./Gemfile.lock .
+COPY ./requirements.txt .
 
 # Install any needed packages specified in requirements.txt
 RUN pip install -r requirements.txt
 
 # note: stay on bundler 1.17 to be travis compatible
-RUN gem install bundler -v 1.17.2 --no-document
-RUN bundle config --global jobs 7
-RUN bundle install
+RUN gem install bundler -v 1.17.2 --no-document && \
+    bundle config --global jobs $(( $(nproc) - 1 )) && \
+    bundle install
+
+# Copy in and set "build_docs.sh" as default image executable for "docker run"
+COPY ./jekyll jekyll
+COPY ./scripts scripts
+COPY ./sphinx sphinx
+ENV PATH=${PATH}:/usr/local/src/scripts
+
+# Install tk-core (python only)
+RUN get-tk-core-packages.sh /usr/local/lib64/python
+ENV PYTHONPATH=${PYTHONPATH}:/usr/local/lib64/python
+
+ENTRYPOINT [ "build_docs.sh" ]

Gemfile

@@ -10,7 +10,7 @@ source "https://rubygems.org"
 gem "jekyll", "~> 3.8.5"
 
 # This is the default theme for new Jekyll sites. You may change this to anything you like.
-gem "just-the-docs", :git => 'https://github.com/shotgunsoftware/just-the-docs.git'
+gem "just-the-docs", :git => 'https://github.com/wwfxuk/just-the-docs.git'
 
 # If you have any plugins, put them here!
 group :jekyll_plugins do

Gemfile.lock

@@ -1,6 +1,6 @@
 GIT
-  remote: https://github.com/shotgunsoftware/just-the-docs.git
-  revision: 54f8f4d79e2c872402f4b3f75693bb3caba44af3
+  remote: https://github.com/wwfxuk/just-the-docs.git
+  revision: e4d057a8a5f057c6aab101071ef7009e10d4c9e9
   specs:
     just-the-docs (0.2.1)
       jekyll (~> 3.8.5)

docs/_data/en/toc_text.yml

@@ -1,8 +1,9 @@
 # Translated text strings used by the table of contents
-# 
+#
 # For documentation, see https://developer.shotgunsoftware.com/tk-doc-generator/authoring/toc/
 #
 
+overview: Overview
 authoring: Authoring docs
 markdown-cheatsheet: Markdown Format
 setting-up: Installation

docs/_data/toc.yml

@@ -4,6 +4,10 @@
 #
 #
 
+- caption: overview
+  children:
+  - page: changelog
+
 - caption: authoring
   children:
   - page: authoring

docs/en/changelog.md

@@ -0,0 +1,55 @@
+---
+layout: default
+title: Change Log/History
+pagename: changelog
+lang: en
+---
+
+Change Log/History
+------------------
+
+See also the [GitHub Releases page][releases]
+
+[releases]: https://github.com/shotgunsoftware/tk-doc-generator/releases
+
+# v1.x.x (changes from v1.0.0+wwfx.0.2.0 to v1.0.0+wwfx.0.3.1)
+
+Functional improvements and fixes from testing
+`tk-doc-generator` (locally using `preview_docs.sh` and on `travis.ci`)
+with `tk-katana` on the [ci-docs](https://github.com/wwfxuk/tk-katana/pull/6)
+branch/PR. See also `tk-katana`'s
+[`gh-pages`](https://github.com/wwfxuk/tk-katana/tree/gh-pages)
+
+- `Dockerfile`:
+    - Moved `Gem*` from `/app` to `/usr/local/src`.
+        - Keeps `/app` clean for `docker run`.
+    - Added default `ENTRYPOINT` to run `build_docs.sh`.
+    - Added `tk-core` as Sphinx `conf.py` requires it.
+    - Optimised `yum install` packages, Ruby curl/untar.
+    - Using `nproc`, replacing hard-coded jobs count.
+
+- `preview_docs.sh`:
+    - Support `-v` instead of `--mount` for `docker run` when using older
+      `docker` version shipped with CentOS 7.
+    - Will not re-build Docker image if `tk-doc-generator` image exists.
+        - Force rebuild using `preview_docs.sh --rebuild`.
+    - Can now be run anywhere, including within `tk-doc-generator`
+
+- `build_docs.sh`:
+    - Fixed configurations using absolute paths.
+    - Fixed inaccurate echo statements
+- `Gemfile*`: Using WWFX `just-the-docs` with
+  [new external links test](https://github.com/shotgunsoftware/just-the-docs/pull/9)
+
+# v1.x.x (v1.0.0+wwfx.0.1.0)
+
+Added this change log as well as minor fixes:
+
+- `.travis.yml`: Changed to WWFX UK `DOC_URL`
+- `Dockerfile`: Fixed `yum clean all` from being part of the `yum install` arguments
+- `build_docs.sh`: Fixed permissions of generated docs from just `root` only
+- `travis-generate-docs.py`: Fallback to `DOC_*` before using dummy URL.
+
+# v1.0.0
+
+Initial release from Shotgun, nothing mentioned by Shotgun.

preview_docs.sh

@@ -7,12 +7,85 @@
 # this software in either electronic or hard copy form.
 #
 
-# Builds a local preview of the documentation in the parent repository that is
-# including tk-doc-generator as a submodule.
+set -eu -o pipefail
 
+
+ARG1="${1:-}"
+case "${ARG1}" in
+    -h|--help)
+        cat << EOF
+Usage:  preview_docs.sh [--rebuild|-h]
+
+Builds a local preview of the documentation in the parent repository that
+includes tk-doc-generator as a sub-module.
+
+Options:
+    --rebuild       Force re-build docker image. By default (for speed),
+                    it will only build a new Docker image if one doesn't exist.
+    -h, --help      Print this help and exit 0.
+
+Environment variables:
+    IMAGE_TAG:
+        Tag for the image Docker builds.
+        Defaults "tk-doc-generator" if not set
+
+    MOUNT_TO:
+        Destination directory which the parent directory this script,
+        the folder above tk-doc-generator, is mounted to in the container.
+        Defaults "/app" if not set
+
+Examples:
+    Typically, this command is run in the parent repository that includes
+    tk-doc-generator as a sub-module.
+
+    To force an image rebuild by running before creating documentation:
+
+        tk-doc-generator/preview_docs.sh --rebuild
+
+    Some environment variables will also influence this script's behaviour.
+    For example, you can run the script like this to build/run the docker image
+    tagged "my-doc-generator", you can run:
+
+        IMAGE_TAG="my-doc-generator" tk-doc-generator/preview_docs.sh
+
+EOF
+        exit
+    ;;
+esac
+
+# Setup useful directory variables for current script's folder/parent folder
 THIS_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
 
-docker build ${THIS_DIR}/../tk-doc-generator -t tk-doc-generator && \
-docker run --mount type=bind,source="${THIS_DIR}/..",target=/app tk-doc-generator \
-/app/tk-doc-generator/scripts/build_docs.sh --url=http://localhost --url-path=${THIS_DIR}/../_build --source=/app/docs --output=/app/_build && \
-echo "Documentation built in ${THIS_DIR}/../_build/index.html"
+
+# Build if image does not exist OR first argument is --rebuild
+IMAGE_TAG="${IMAGE_TAG:-tk-doc-generator}"
+if [ -z "$(docker images --quiet ${IMAGE_TAG})" -o "${ARG1}" == "--rebuild" ]
+then
+    docker build --tag "${IMAGE_TAG}" ${THIS_DIR}
+else
+    echo "'${IMAGE_TAG}' docker image already built"
+    echo "To force a re-build, try running this script with --rebuild flag"
+    echo
+fi
+
+
+# Setup mount/volume flags depending on which one current docker supports
+MOUNT_TO="${MOUNT_TO:-/app}"
+if ( docker run --help | grep --quiet -- --mount )
+then
+    MOUNT_FLAGS='--mount '"type=bind,source=$(pwd),target=${MOUNT_TO}"
+else
+    MOUNT_FLAGS='-v '"$(pwd):${MOUNT_TO}"
+fi
+
+
+# Finally, perform the document generation in container
+docker run --rm \
+    ${MOUNT_FLAGS} \
+    ${IMAGE_TAG} \
+    --url="http://localhost" \
+    --url-path="$(pwd)/_build" \
+    --source="${MOUNT_TO}/docs" \
+    --output="${MOUNT_TO}/_build"
+
+echo "Documentation built. Open in web-browser: $(pwd)/_build/index.html"

scripts/build_docs.sh

@@ -53,8 +53,11 @@ echo "---------------------------------------------------"
 
 THIS_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
 
-TMP_FOLDER=${THIS_DIR}/../_doc_generator_tmp
-TMP_BUILD_FOLDER=${TMP_FOLDER}/markdown_src
+TK_DOC_GEN_SRC="$(readlink -m ${THIS_DIR}/..)"  # contains Gemfile, jekyll, etc
+OUR_REPO_ROOT="$(readlink -m ${SOURCE}/..)"  # user's project root folder
+
+TMP_FOLDER="${TK_DOC_GEN_SRC}/_doc_generator_tmp"
+TMP_BUILD_FOLDER="${TMP_FOLDER}/markdown_src"
 
 echo ""
 echo "Intermediate files will be written to '${TMP_FOLDER}'."
@@ -67,35 +70,32 @@ echo "Cleaning out final build location '${OUTPUT}'..."
 rm -rf ${OUTPUT}
 
 echo "Creating build location '${TMP_BUILD_FOLDER}'..."
-mkdir -p ${TMP_BUILD_FOLDER}
+mkdir -p ${TMP_BUILD_FOLDER}/_plugins
 
-echo "Copying source files into '${TMP_FOLDER}'..."
+echo "Copying source files into '${TMP_BUILD_FOLDER}'..."
 cp -r ${SOURCE}/* ${TMP_BUILD_FOLDER}
 
-echo "Copying plugins into '${TMP_FOLDER}/_plugins'..."
-mkdir -p ${TMP_BUILD_FOLDER}/_plugins
-cp -nr ${THIS_DIR}/../jekyll/_plugins/* ${TMP_BUILD_FOLDER}/_plugins
+echo "Copying plugins into '${TMP_BUILD_FOLDER}/_plugins'..."
+cp -nr ${TK_DOC_GEN_SRC}/jekyll/_plugins/* ${TMP_BUILD_FOLDER}/_plugins
 
 echo "Running Sphinx RST -> Markdown build process..."
 python ${THIS_DIR}/build_sphinx.py ${TMP_BUILD_FOLDER}
 
 echo "Running Jekyll to generate html from markdown..."
+CONFIGS="${TK_DOC_GEN_SRC}/jekyll/_config.yml"
 
 # see if an external override config file exists
-OVERRIDE_CONFIG=${THIS_DIR}/../../jekyll_config.yml
-
-if [ -e "$OVERRIDE_CONFIG" ]; then
+OVERRIDE_CONFIG=${OUR_REPO_ROOT}/jekyll_config.yml
+if [ -e "${OVERRIDE_CONFIG}" ]
+then
     echo "using override config from ${OVERRIDE_CONFIG}..."
-    BUNDLE_GEMFILE=${THIS_DIR}/../Gemfile JEKYLL_ENV=production \
-    bundle exec jekyll build \
-    --baseurl "${URLPATH}" --config ${THIS_DIR}/../jekyll/_config.yml,${OVERRIDE_CONFIG} \
-    --source "${TMP_BUILD_FOLDER}" --destination "${OUTPUT}"
-else
-    BUNDLE_GEMFILE=${THIS_DIR}/../Gemfile JEKYLL_ENV=production \
+    CONFIGS="${CONFIGS},${OVERRIDE_CONFIG}"
+fi
+
+BUNDLE_GEMFILE=${TK_DOC_GEN_SRC}/Gemfile JEKYLL_ENV=production \
     bundle exec jekyll build \
-    --baseurl "${URLPATH}" --config ${THIS_DIR}/../jekyll/_config.yml \
+    --baseurl "${URLPATH}" --config "${CONFIGS}" \
     --source "${TMP_BUILD_FOLDER}" --destination "${OUTPUT}"
-fi
 
 echo "------------------------------------------------------"
 echo "Build completed."