sphinx-deployment

Automatic setup and deployment for sphinx docs.

This project is intended to be used to deploy sphinx project on:

• Github Pages
• Rsync
• PaaS services: heroku, etc.

Usage

1. $ make generate

For generating contents, alias for $ make html

2. $ make deploy

For short-cut deployment, it could be $ make deploy_gh_pages, $ make deploy_rsync or $ make deploy_heroku basing on the configuration of DEPLOY_DEFAULT.

3. $ make gen_deploy

For short-cut generation and deployment: $ make generate and then $ make deploy.

4. $ make setup_gh_pages

For the first time only to create $(DEPLOY_DIR) to track $(DEPLOY_BRANCH). This is used for github pages deployment.

5. $ make setup_heroku

For the first time only to create $(DEPLOY_DIR_HEROKU to track the Heroku repo's master branch. This is used for heroku deployment.

6. $ make deploy_gh_pages

For deploying with github pages only.

7. $ make deploy_rsync

For deploying with rsync only.

8. $ make deploy_heroku

For deploying with heroku only.

9. $ make livehtml

For auto-building the documentation when a change is detected thanks to https://pypi.org/project/sphinx-autobuild/

10. $ make build_docker_image

To build the production docker image for the docs site, for example:

$ make build_docker_image DOCKER_IMG_TAG=company/project-docs:develop

Installation

1. Bash script

Just run this bash script from your root git repository project and it's enough.

You need to specify the <docs_path> to your sphinx docs directory:

$ cd <your_project>
$ wget https://raw.githubusercontent.com/teracyhq/sphinx-deployment/master/scripts/spxd.sh && chmod +x ./spxd.sh && ./spxd.sh -p <docs_path>

For example:

$ cd my_project
$ wget https://raw.githubusercontent.com/teracyhq/sphinx-deployment/master/scripts/spxd.sh && chmod +x ./spxd.sh && ./spxd.sh -p ./docs

2. Manual

a. You need to copy these following files to your sphinx directory:

• docs/requirements
• docs/sphinx_deployment.mk
• docs/rsync_exclude
• docs/.deploy_heroku/*
• docs/.gitignore

b. Include sphinx_deployment.mk to your Makefile:

• Add the content below to your Makefile:

include sphinx_deployment.mk

• Or do with commands on terminal:

echo '' >> Makefile
echo 'include sphinx_deployment.mk' >> Makefile

c.. To build with travis-ci, you need to copy these following files to your root project directory:

• .travis.yml
• .travis/setup.sh

Auto-build with docker-compose

Make sure docker and docker-compose are installed and running.

$ docker-compose up -d
$ echo open http://localhost:`docker port docs_docs_1 80 | grep -o [0-9]*$` to view the docs
open http://localhost:32770 to view the docs

Check the output from the command above to open the docs site. The docs site will auto reload when changes are made to the docs files.

To see the docs site logs, execute the following command:

$ docker-compose logs -f docs

Configuration

You need to configure these following deployment configurations following your project settings on sphinx_deployment.mk file.

# Deployment configurations from sphinx_deployment project

# default deployment when $ make deploy
# deploy_gh_pages                            : to $ make deploy_gh_pages
# deploy_rsync                               : to $ make deploy_rsync
# deploy_heroku                              : to $ make deploy_heroku
# deploy_gh_pages deploy_rsync deploy_heroku : to $ make deploy_gh_pages then $ make deploy_rsync
#                                              and then $ make deploy_heroku
# default value: deploy_gh_pages
ifndef DEPLOY_DEFAULT
DEPLOY_DEFAULT = deploy_gh_pages
endif

# The deployment directory to be deployed
ifndef DEPLOY_DIR
DEPLOY_DIR      = _deploy
endif

# The heroku deployment directory to be deployed
# we must create this separated dir to avoid any conflict with _deploy (rsync and gh_pages)
ifndef DEPLOY_DIR_HEROKU
DEPLOY_DIR_HEROKU = _deploy_heroku
endif

# Copy contents from $(BUILDDIR) to $(DEPLOY_DIR)/$(DEPLOY_HTML_DIR) directory
ifndef DEPLOY_HTML_DIR
DEPLOY_HTML_DIR = docs
endif


## -- Rsync Deploy config -- ##
# Be sure your public key is listed in your server's ~/.ssh/authorized_keys file
ifndef SSH_USER
SSH_USER       = user@domain.com
endif

ifndef SSH_PORT
SSH_PORT       = 22
endif

ifndef DOCUMENT_ROOT
DOCUMENT_ROOT  = ~/website.com/
endif

#If you choose to delete on sync, rsync will create a 1:1 match
ifndef RSYNC_DELETE
RSYNC_DELETE   = false
endif

# Any extra arguments to pass to rsync
ifndef RSYNC_ARGS
RSYNC_ARGS     =
endif

## -- Github Pages Deploy config -- ##

# Configure the right deployment branch
ifndef DEPLOY_BRANCH_GITHUB
DEPLOY_BRANCH_GITHUB = gh-pages
endif

#if REPO_URL_GITHUB was NOT defined by travis-ci
ifndef REPO_URL_GITHUB
# Configure your right github project repo
# REPO_URL       = git@github.com:teracy-official/sphinx-deployment.git
endif

## -- Heroku Deployment Config -- ##

ifndef REPO_URL_HEROKU
# Configure your right heroku repo
# REPO_URL_HEROKU = git@heroku.com:spxd.git
endif

## -- Docker Config -- ##

ifndef DOCKER_IMG_TAG
# Configure your default docker image tag
DOCKER_IMG_TAG = sphinx-deployment/docs:develop
endif

## end deployment configuration, don't edit anything below this line ##
#######################################################################

Continuous Integration Build

1. travis-ci

Move .travis.yml file to your root repository project, and configure it following its instruction there. There is a supported .travis/setup.sh to export variables for Makefile depending on the being-built branch.

To configure secure token for travis-ci, please read the similar step described at http://blog.teracy.com/2013/08/03/how-to-start-blogging-easily-with-octopress-and-teracy-dev/

2. jenkins

//TODO

Authors and contributors

• Hoat Le: http://github.com/hoatle

• Many thanks to http://octopress.org/docs/deploying/ for inspiration.

License

BSD License

Copyright (c) Teracy, Inc. and individual contributors.
All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

    1. Redistributions of source code must retain the above copyright notice,
       this list of conditions and the following disclaimer.

    2. Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.

    3. Neither the name of Teracy, Inc. nor the names of its contributors may be used
       to endorse or promote products derived from this software without
       specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.