Merge pull request #6 from titan-data/master

update from fork

.github/workflows/docs-push.yml

@@ -0,0 +1,42 @@
+name: Push to Development Docs
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'docs/*'
+      - 'docs/*/*'
+      - 'docs/*/*/*'
+      - 'docs/*/*/*/*'
+
+jobs:
+  build:
+    name: Build Documentation
+    runs-on: ubuntu-18.04
+    steps:
+      - uses: actions/checkout@v1
+      - name: Configure GitHub SSH access
+        uses: webfactory/[email protected]
+        with:
+          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
+      - name: Install virtualenv
+        run: sudo pip3 install virtualenv
+      - name: Build documentation
+        run: |
+          export PATH=/usr/local/bin:$PATH
+          ./docs/build.sh -r development -v development
+      - name: Clone titan-data.github.io
+        run: |
+          git clone [email protected]:titan-data/titan-data.github.io
+          cd ./titan-data.github.io && git log -1
+      - name: Configure git user
+        run: |
+          cd ./titan-data.github.io
+          git config user.name "titan-docs"
+          git config user.email "[email protected]"
+      - name: Publish docs
+        run: ./docs/publish.sh -v development ./titan-data.github.io
+      - name: Push docs
+        run: |
+          cd ./titan-data.github.io
+          git push

.github/workflows/docs-release.yml

@@ -0,0 +1,34 @@
+name: Push to Release Docs
+on: create
+
+jobs:
+  build:
+    name: Build Documentation
+    runs-on: ubuntu-18.04
+    steps:
+      - uses: actions/checkout@v1
+      - name: Configure GitHub SSH access
+        uses: webfactory/[email protected]
+        with:
+          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
+      - name: Install virtualenv
+        run: sudo pip3 install virtualenv
+      - name: Build documentation
+        run: |
+          export PATH=/usr/local/bin:$PATH
+          ./docs/build.sh -r official -v ${GITHUB_REF#refs/tags/}
+      - name: Clone titan-data.github.io
+        run: |
+          git clone [email protected]:titan-data/titan-data.github.io
+          cd ./titan-data.github.io && git log -1
+      - name: Configure git user
+        run: |
+          cd ./titan-data.github.io
+          git config user.name "titan-docs"
+          git config user.email "[email protected]"
+      - name: Publish docs
+        run: ./docs/publish.sh -l -f -v ${GITHUB_REF#refs/tags/} ./titan-data.github.io
+      - name: Push docs
+        run: |
+          cd ./titan-data.github.io
+          git push

.gitignore

@@ -18,4 +18,7 @@ releases
 /.env
 
 # Jenkins
-.gradle
+.gradle
+
+# Docs files
+/docs/build

docs/build.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+
+#
+# This is a simple wrapper around the sphinx build that will install the
+# necessary python requirements, set sphinx configuration values, etc. It
+# places the output in build/out. The followign options are supported:
+#
+#   -r release    Set the release type. Must be one of "development" or
+#                 "official". The former will place a warning indicating
+#                 that the documentation may not be reflective of what's
+#                 currently available.
+#
+#   -v version    Version string to use. Defaults to "latest".
+#
+
+set -xe
+
+BUILD_DIR=$(dirname $0)/build
+VENV_DIR=$BUILD_DIR/venv
+OUT_DIR=$BUILD_DIR/out
+SRC_DIR=$(dirname $0)/src
+
+function usage() {
+  echo "Usage: $0 [-r development|official] [-v version]" 1>&2
+  exit 2
+}
+
+release_type=development
+version=latest
+
+while getopts ":r:v:" o; do
+  case "${o}" in
+    r)
+      release_type=$OPTARG
+      ;;
+    v)
+      version=$OPTARG
+      ;;
+    *)
+      usage
+      ;;
+  esac
+done
+
+
+mkdir -p $OUT_DIR
+
+#
+# Create python environment
+#
+if [[ -z $VIRTUAL_ENV ]]; then
+  if [[ ! -d $VENV_DIR ]]; then
+    virtualenv $VENV_DIR --no-site-packages --python=python3
+  fi
+  source $VENV_DIR/bin/activate
+fi
+
+#
+# Install python dependencies
+#
+pip3 install -r $(dirname $0)/requirements.txt
+
+#
+# Run sphinx
+#
+rm -rf $OUT_DIR
+sphinx-build -W --keep-going $SRC_DIR $OUT_DIR -D release_type=$release_type \
+  -D version=$version
+
+#
+# Sphinx's use of _static and friends is problematic for github pages, which is
+# run through jekyll. While we could move to an external system like Netlify,
+# or build CI/CD to publish a static site somewhere else, simply renaming these
+# directories is sufficient for now.
+#
+mv $OUT_DIR/_static $OUT_DIR/static
+mv $OUT_DIR/_sources $OUT_DIR/sources
+find $OUT_DIR -name '*.html' -exec sed -i -e 's/_static/static/g' {} \;
+find $OUT_DIR -name '*.html' -exec sed -i -e 's/_sources/sources/g' {} \;

docs/publish.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+
+#
+# This script handles publishing the previously built docs into a clone of
+# the titan-data.github.io repository. It takes the following arguments:
+#
+# ./publish.sh [-v version] [-f] [-d] [-l] <path>
+#
+#     -v version  Specify the version to use. Defaults to "development".
+#
+#     -f          Force rebuild. By default, the script will look at the last
+#                 commit hash to touch the docs directory, and skip updating
+#                 the docs if the previous version used the same hash.
+#
+#     -d          Dry run. This will update the contents of the docs site,
+#                 but won't commit the result.
+#
+#     -l          Update latest version to point to current verison.
+#
+#     path        Path to the root of the titan-data.github.io repository.
+#
+
+set -xe
+
+WORKING_DIR=$(realpath $PWD)
+DOCS_DIR=$(realpath $(dirname $0))
+BUILD_DIR=$DOCS_DIR/build
+SRC_DIR=$BUILD_DIR/out
+
+function usage() {
+  echo "Usage: $0 [-v version] [-f] [-d] path" 1>&2
+  exit 2
+}
+
+function die() {
+  echo $* 1>&2
+  exit 1
+}
+
+version=development
+force=false
+dry_run=false
+update_latest=false
+
+while getopts ":fdlv:" o; do
+  case "${o}" in
+    d)
+      dry_run=true
+      ;;
+    f)
+      force=true
+      ;;
+    l)
+      update_latest=true
+      ;;
+    v)
+      version=$OPTARG
+      ;;
+    *)
+      usage
+      ;;
+  esac
+done
+
+shift $((OPTIND-1))
+dest=$(realpath $1)
+
+[[ -d $dest ]] || die "Missing or invalid destination directory"
+
+VERSION_DIR=$dest/docs/version
+
+#
+# Check to see if we need to rebuild the docs.
+#
+function check_hash() {
+  local vers=$1
+  cd $WORKING_DIR
+  CURRENT_HASH=$(git log --pretty=format:%H -n 1 $DOCS_DIR)
+  if [[ $force = false ]]; then
+    if [[ -f $VERSION_DIR/$vers/hash ]]; then
+      local previous_hash=$(cat $VERSION_DIR/$vers/hash)
+
+      if [[ $previous_hash = $CURRENT_HASH ]]; then
+        echo "Content hasn't changed with hash $previous_hash, skipping"
+        exit 0
+      fi
+    fi
+  fi
+}
+
+#
+# Copy over our source, with hash, and add to git
+#
+function copy_docs() {
+  local vers=$1
+  local dst_dir=$VERSION_DIR/$vers
+  cd $WORKING_DIR
+  if [[ -d $dst_dir ]]; then
+    cd $VERSION_DIR && git rm -rf --ignore-unmatch $vers
+  fi
+  cd $WORKING_DIR
+  mkdir -p $VERSION_DIR
+  rm -rf $dst_dir
+  cp -r $SRC_DIR $dst_dir
+  echo $CURRENT_HASH > $dst_dir/hash
+  cd $dst_dir && git add .
+}
+
+#
+# Generate docs.yml data
+#
+function generate_config() {
+  cd $dest
+  DOCS_DATA=_data/docs.yml
+  if [[ $update_latest = true ]]; then
+    latest=$version
+  else
+    current_latest=$(grep "^latest: " $DOCS_DATA)
+    latest=${current_latest#latest: }
+  fi
+  echo "latest: $latest" > $DOCS_DATA
+  echo "versions:" >> $DOCS_DATA
+  for v in $(ls -1 $VERSION_DIR | sort -r --version-sort); do
+    [[ $v != "development" && $v != "latest" ]] && echo "  - $v" >> $DOCS_DATA
+  done
+  git add $DOCS_DATA
+}
+
+function commit() {
+   cd $dest
+   git commit -m "docs build $version $CURRENT_HASH"
+   git status
+}
+
+check_hash $version
+copy_docs $version
+[[ $update_latest = true ]] && copy_docs latest
+generate_config
+commit

docs/requirements.txt

@@ -0,0 +1,3 @@
+recommonmark==0.6.0
+sphinx==2.2.0
+sphinx-rtd-theme==0.4.3

docs/src/_static/css/titan.css

@@ -0,0 +1,16 @@
+@import url("theme.css");
+
+/*Changing content max-width 100% ( 800px is default )*/
+.wy-nav-content {
+  max-width: 100% !important;
+}
+
+/* Splits a long line descriptions in tables in to multiple lines */
+.wy-table-responsive table td, .wy-table-responsive table th {
+  white-space: normal !important;
+}
+
+/* align multi line csv table columns */
+table.docutils div.line-block {
+    margin-left: 0;
+}

docs/src/cli/cli.rst

@@ -0,0 +1,57 @@
+.. _cli:
+
+Command Line Reference
+======================
+
+The ``titan`` command line is the primary tool for managing repositories and
+commits. While there are a number of detailed subcommands, there are some
+global options as well.
+
+.. note::
+
+  The ``--help`` option can be used to provide more detail about subcommands
+  and their options, such as ``titan run --help`` or ``titan remote --help``.
+
+Syntax
+------
+
+::
+
+   titan --help
+   titan --version
+   titan subcommand ...
+
+Options
+-------
+
+--version       Display the titan version and exit.
+--help, -h      Display available subcommands.
+
+Subcommands
+-----------
+
+.. toctree::
+   :maxdepth: 1
+
+   cmd/abort
+   cmd/checkout
+   cmd/clone
+   cmd/commit
+   cmd/cp
+   cmd/install
+   cmd/log
+   cmd/ls
+   cmd/migrate
+   cmd/pull
+   cmd/push
+   cmd/remote_add
+   cmd/remote_log
+   cmd/remote_ls
+   cmd/remote_rm
+   cmd/rm
+   cmd/run
+   cmd/start
+   cmd/status
+   cmd/stop
+   cmd/uninstall
+   cmd/upgrade

docs/src/cli/cmd/abort.rst

@@ -0,0 +1,6 @@
+.. _cli_cmd_abort:
+
+titan abort
+===========
+
+Coming soon!