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.
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.
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.github.com/teracy-official/sphinx-deployment/master/scripts/spxd.sh && chmod +x ./spxd.sh && ./spxd.sh -p <docs_path>For example:
$ cd my_project
$ wget https://raw.github.com/teracy-official/sphinx-deployment/master/scripts/spxd.sh && chmod +x ./spxd.sh && ./spxd.sh -p ./docs2. Manual
a. You need to copy these following files to your sphinx directory:
docs/requirementsdocs/sphinx_deployment.mkdocs/rsync_excludedocs/.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' >> Makefilec.. To build with travis-ci, you need to copy these following files to your root project directory:
.travis.yml.travis/setup.sh
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 = [email protected]
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 = [email protected]:teracy-official/sphinx-deployment.git
endif
## -- Heroku Deployment Config -- ##
ifndef REPO_URL_HEROKU
# Configure your right heroku repo
# REPO_URL_HEROKU = [email protected]:spxd.git
endif
## end deployment configuration, don't edit anything below this line ##
#######################################################################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
-
Hoat Le: http://github.com/hoatle
-
Many thanks to http://octopress.org/docs/deploying/ for inspiration.
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.