Minor yum, permission and URL fixes

.travis.yml

@@ -45,7 +45,7 @@ script:
   - python ./travis-generate-docs.py
 
 deploy:
-  # When commiting to master, auto-deploy to github-pages
+  # When committing to master, auto-deploy to github-pages
   # This will copy the contents of the _build folder to gh-pages branch and push
 - provider: pages
   local-dir: ./_build

Dockerfile

@@ -18,30 +18,30 @@ 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 \
+        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 && \
     yum clean all
 
 # Ruby

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,25 @@
+---
+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
+
+Added this change log as well as minor fixes:
+
+- `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.

scripts/build_docs.sh

@@ -97,6 +97,8 @@ else
     --source "${TMP_BUILD_FOLDER}" --destination "${OUTPUT}"
 fi
 
+# Local preview_docs.sh (Docker): allow non-root users to modify generated docs
+chmod -R 'a+rwX' "${OUTPUT}"
 echo "------------------------------------------------------"
 echo "Build completed."
 echo "------------------------------------------------------"

travis-generate-docs.py

@@ -124,27 +124,30 @@ def main():
     current_branch = os.environ.get("TRAVIS_BRANCH")
     inside_pr = os.environ.get("TRAVIS_PULL_REQUEST") != "false"
 
-    # first figure out i we are on master or in a PR.
+    # first figure out if we are on master or in a PR.
     if current_branch != "master" or inside_pr:
-        # we are in a PR.
-        log.info("Inside a pull request.")
+        log.info("Inside a pull request (or not master branch).")
 
-        # see if we have access to an AWS bucket
-        if "S3_BUCKET" in os.environ and "S3_WEB_URL" in os.environ:
+        # See if we have access to an AWS bucket
+        s3_bucket = os.getenv("S3_BUCKET", default=None)
+        target_url = os.getenv("S3_WEB_URL", default=None)
+        if s3_bucket and target_url:
             log.info("Detected AWS S3 bucket for preview workflow.")
-
-            s3_bucket = os.environ["S3_BUCKET"]
-            target_url = os.environ["S3_WEB_URL"]
-            target_url_path = "/tk-doc-generator/{commit}".format(
-                commit=os.environ["TRAVIS_COMMIT"]
-            )
-
+            target_url_path = "/tk-doc-generator/{env[TRAVIS_COMMIT]}"
+            target_url_path = target_url_path.format(env=os.environ)
         else:
             log.warning("No S3_BUCKET and S3_WEB_URL detected in environment. "
                         "No S3 preview will be generated")
-            s3_bucket = None
-            # enter dummy paths so we can at least build
-            # the docs to check for errors
+
+        # Then try use DOC_* for target
+        target_url = os.getenv("DOC_URL", default=None)
+        target_url_path = os.getenv("DOC_PATH", default=None)
+        if target_url and target_url_path:
+            log.info("Using DOC_URL/PATH.")
+        else:
+            # Fall back to using root directly on dummy domain url
+            log.warning("Using dummy paths so we can at least build the docs "
+                        "to check for errors")
             target_url = "https://dummy.url.com"
             target_url_path = "/"
 
@@ -160,12 +163,14 @@ def main():
         )
         execute_external_command(doc_command)
 
-        if s3_bucket:
+        aws_access_key = os.getenv("AWS_S3_ACCESS_KEY", default=None)
+        aws_access_token = os.getenv("AWS_S3_ACCESS_TOKEN", default=None)
+        if s3_bucket and aws_access_key and aws_access_token:
             log.info("Uploading build result to S3...")
             s3_client = boto3.client(
                 "s3",
-                aws_access_key_id=os.environ["AWS_S3_ACCESS_KEY"],
-                aws_secret_access_key=os.environ["AWS_S3_ACCESS_TOKEN"]
+                aws_access_key=aws_access_key,
+                aws_access_token=aws_access_token
             )
 
             # note: skip the first slash when uploading to S3