https://github.com/teracyhq/sphinx-deployment
automatic setup and deployment for sphinx docs
https://github.com/teracyhq/sphinx-deployment
gh-pages github-page heroku rsync shell sphinx sphinx-deployment sphinx-doc
Last synced: 10 months ago
JSON representation
automatic setup and deployment for sphinx docs
- Host: GitHub
- URL: https://github.com/teracyhq/sphinx-deployment
- Owner: teracyhq
- License: bsd-3-clause
- Created: 2013-08-17T16:35:37.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2019-03-01T06:40:22.000Z (almost 7 years ago)
- Last Synced: 2025-04-01T02:48:31.126Z (11 months ago)
- Topics: gh-pages, github-page, heroku, rsync, shell, sphinx, sphinx-deployment, sphinx-doc
- Language: Shell
- Homepage: http://blog.teracy.com/tags/sphinx-deployment/
- Size: 54.7 KB
- Stars: 26
- Watchers: 3
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
sphinx-deployment
=================
Automatic setup and deployment for [sphinx][] docs.
This project is intended to be used to deploy [sphinx][] project on:
- [Github Pages](https://help.github.com/categories/20/articles)
- [Rsync](http://en.wikipedia.org/wiki/Rsync)
- PaaS services: [heroku](http://heroku.com/), 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 `` to your sphinx docs directory:
``` bash
$ cd
$ wget https://raw.githubusercontent.com/teracyhq/sphinx-deployment/master/scripts/spxd.sh && chmod +x ./spxd.sh && ./spxd.sh -p
```
For example:
``` bash
$ 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:
``` bash
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.
```bash
$ 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:
```bash
$ docker-compose logs -f docs
```
Configuration
-------------
You need to configure these following deployment configurations following your project settings on
`sphinx_deployment.mk` file.
``` Makefile
# 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.
```
[sphinx]: http://sphinx-doc.org