Skip to content

Commit 11da3a9

Browse files
freeman-labfreeman-lab
committed
Add one-step gh-pages deployment
1 parent a8a1be7 commit 11da3a9

File tree

6 files changed

+494
-12
lines changed

6 files changed

+494
-12
lines changed

‎.travis.yml

+17-8
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,21 @@
11
language: python
22

3-
python:
4-
- "2.7"
5-
- "3.4"
3+
before_script:
4+
- git config --global user.name "Teracy" # Configure your git user.name here
5+
- git config --global user.email "[email protected]" # Configure your git user.email here
6+
- export REPO_URL_GITHUB="https://[email protected]/$GH_REPO.git"
7+
- . ./.travis/setup.sh # make any change needed for setup.sh
8+
- echo $DEPLOY_HTML_DIR
69

7-
install:
8-
- pip install .
9-
- pip install -r requirements.txt
10+
after_script:
11+
- sudo pip install -r docs/requirements.txt --use-mirrors # change this to the right project path
12+
- cd docs
13+
- make setup_gh_pages
14+
- make generate
15+
- make deploy
1016

11-
script:
12-
- py.test --host http://lightning-python-test.herokuapp.com
17+
env:
18+
global:
19+
- GH_REPO="teracy-official/sphinx-deployment" #change this to your right project
20+
# configure the right travis-ci secure key, see sphinx-deployment/README for more details
21+
#- secure: im3gWbsEF135C0jKlOIRJUa1tgtsCAaqwGDSpzwe/fnTosqystNE+mhvFfERmy1K4qRg0cbRYGd8L6pP/V7RR3GMqFX4h5wexZeKsCN895S0d7QIWUmw2yJ3+mvk/g+E6q56tORzhKzKVRef5VWkk84EOKrZ/KIeoVpKVAlVR1s=

‎.travis/setup.sh

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
#!/bin/bash
2+
3+
#setup travis-ci configuration basing one the being-built branch
4+
5+
if [[ $TRAVIS_BRANCH == 'master' ]] ; then
6+
export DEPLOY_HTML_DIR=docs
7+
elif [[ $TRAVIS_BRANCH == 'develop' ]] ; then
8+
export DEPLOY_HTML_DIR=docs/develop
9+
elif [[ $TRAVIS_BRANCH =~ ^v[0-9.]+$ ]]; then
10+
export DEPLOY_HTML_DIR=docs/${TRAVIS_BRANCH:1}
11+
else
12+
export DEPLOY_HTML_DIR=docs/$TRAVIS_BRANCH
13+
fi

‎doc/.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# default ignored by sphinx-deployment
2+
_deploy
3+
_deploy_heroku

‎doc/README_sphinx_deployment.md

+251
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
1+
sphinx-deployment
2+
=================
3+
4+
Automatic setup and deployment for [sphinx][] docs.
5+
6+
This project is intended to be used to deploy [sphinx][] project on:
7+
8+
- [Github Pages](https://help.github.com/categories/20/articles)
9+
- [Rsync](http://en.wikipedia.org/wiki/Rsync)
10+
- PaaS services: [heroku](http://heroku.com/), etc.
11+
12+
Usage
13+
-----
14+
15+
**1. `$ make generate`**
16+
17+
For generating contents, alias for `$ make html`
18+
19+
**2. `$ make deploy`**
20+
21+
For short-cut deployment, it could be `$ make deploy_gh_pages`, `$ make deploy_rsync` or
22+
`$ make deploy_heroku` basing on the configuration of `DEPLOY_DEFAULT`.
23+
24+
**3. `$ make gen_deploy`**
25+
26+
For short-cut generation and deployment: `$ make generate` and then `$ make deploy`.
27+
28+
**4. `$ make setup_gh_pages`**
29+
30+
For the first time only to create `$(DEPLOY_DIR)` to track `$(DEPLOY_BRANCH)`. This is used for
31+
github pages deployment.
32+
33+
**5. `$ make setup_heroku`**
34+
35+
For the first time only to create `$(DEPLOY_DIR_HEROKU` to track the Heroku repo's master branch.
36+
This is used for heroku deployment.
37+
38+
**6. `$ make deploy_gh_pages`**
39+
40+
For deploying with github pages only.
41+
42+
**7. `$ make deploy_rsync`**
43+
44+
For deploying with rsync only.
45+
46+
**8. `$ make deploy_heroku`**
47+
48+
For deploying with heroku only.
49+
50+
51+
Installation
52+
------------
53+
54+
**1. Bash script**
55+
56+
Just run this bash script from your root git repository project and it's enough.
57+
58+
You need to specify the `<docs_path>` to your sphinx docs directory:
59+
60+
``` bash
61+
$ cd <your_project>
62+
$ wget https://raw.github.com/teracy-official/sphinx-deployment/master/scripts/spxd.sh && chmod +x ./spxd.sh && ./spxd.sh -p <docs_path>
63+
```
64+
65+
For example:
66+
67+
``` bash
68+
$ cd my_project
69+
$ wget https://raw.github.com/teracy-official/sphinx-deployment/master/scripts/spxd.sh && chmod +x ./spxd.sh && ./spxd.sh -p ./docs
70+
```
71+
72+
**2. Manual**
73+
74+
a. You need to copy these following files to your [sphinx][] directory:
75+
76+
- `docs/requirements`
77+
- `docs/sphinx_deployment.mk`
78+
- `docs/rsync_exclude`
79+
- `docs/.deploy_heroku/*`
80+
- `docs/.gitignore`
81+
82+
b. Include `sphinx_deployment.mk` to your `Makefile`:
83+
84+
- Add the content below to your `Makefile`:
85+
86+
```
87+
include sphinx_deployment.mk
88+
```
89+
90+
- Or do with commands on terminal:
91+
92+
``` bash
93+
echo '' >> Makefile
94+
echo 'include sphinx_deployment.mk' >> Makefile
95+
```
96+
97+
98+
c.. To build with `travis-ci`, you need to copy these following files to your root project directory:
99+
100+
- `.travis.yml`
101+
- `.travis/setup.sh`
102+
103+
104+
Configuration
105+
-------------
106+
107+
You need to configure these following deployment configurations following your project settings on
108+
`sphinx_deployment.mk` file.
109+
110+
``` Makefile
111+
# Deployment configurations from sphinx_deployment project
112+
113+
# default deployment when $ make deploy
114+
# deploy_gh_pages : to $ make deploy_gh_pages
115+
# deploy_rsync : to $ make deploy_rsync
116+
# deploy_heroku : to $ make deploy_heroku
117+
# deploy_gh_pages deploy_rsync deploy_heroku : to $ make deploy_gh_pages then $ make deploy_rsync
118+
# and then $ make deploy_heroku
119+
# default value: deploy_gh_pages
120+
ifndef DEPLOY_DEFAULT
121+
DEPLOY_DEFAULT = deploy_gh_pages
122+
endif
123+
124+
# The deployment directory to be deployed
125+
ifndef DEPLOY_DIR
126+
DEPLOY_DIR = _deploy
127+
endif
128+
129+
# The heroku deployment directory to be deployed
130+
# we must create this separated dir to avoid any conflict with _deploy (rsync and gh_pages)
131+
ifndef DEPLOY_DIR_HEROKU
132+
DEPLOY_DIR_HEROKU = _deploy_heroku
133+
endif
134+
135+
# Copy contents from $(BUILDDIR) to $(DEPLOY_DIR)/$(DEPLOY_HTML_DIR) directory
136+
ifndef DEPLOY_HTML_DIR
137+
DEPLOY_HTML_DIR = docs
138+
endif
139+
140+
141+
## -- Rsync Deploy config -- ##
142+
# Be sure your public key is listed in your server's ~/.ssh/authorized_keys file
143+
ifndef SSH_USER
144+
SSH_USER = [email protected]
145+
endif
146+
147+
ifndef SSH_PORT
148+
SSH_PORT = 22
149+
endif
150+
151+
ifndef DOCUMENT_ROOT
152+
DOCUMENT_ROOT = ~/website.com/
153+
endif
154+
155+
#If you choose to delete on sync, rsync will create a 1:1 match
156+
ifndef RSYNC_DELETE
157+
RSYNC_DELETE = false
158+
endif
159+
160+
# Any extra arguments to pass to rsync
161+
ifndef RSYNC_ARGS
162+
RSYNC_ARGS =
163+
endif
164+
165+
## -- Github Pages Deploy config -- ##
166+
167+
# Configure the right deployment branch
168+
ifndef DEPLOY_BRANCH_GITHUB
169+
DEPLOY_BRANCH_GITHUB = gh-pages
170+
endif
171+
172+
#if REPO_URL_GITHUB was NOT defined by travis-ci
173+
ifndef REPO_URL_GITHUB
174+
# Configure your right github project repo
175+
# REPO_URL = [email protected]:teracy-official/sphinx-deployment.git
176+
endif
177+
178+
## -- Heroku Deployment Config -- ##
179+
180+
ifndef REPO_URL_HEROKU
181+
# Configure your right heroku repo
182+
# REPO_URL_HEROKU = [email protected]:spxd.git
183+
endif
184+
185+
186+
## end deployment configuration, don't edit anything below this line ##
187+
#######################################################################
188+
```
189+
190+
Continuous Integration Build
191+
----------------------------
192+
193+
**1. `travis-ci`**
194+
195+
Move `.travis.yml` file to your root repository project, and configure it following its
196+
instruction there. There is a supported `.travis/setup.sh` to export variables for `Makefile`
197+
depending on the being-built branch.
198+
199+
To configure secure token for `travis-ci`, please read the similar step described at
200+
http://blog.teracy.com/2013/08/03/how-to-start-blogging-easily-with-octopress-and-teracy-dev/
201+
202+
203+
**2. `jenkins`**
204+
205+
//TODO
206+
207+
208+
Authors and contributors
209+
------------------------
210+
211+
- Hoat Le: http://github.com/hoatle
212+
213+
- Many thanks to http://octopress.org/docs/deploying/ for inspiration.
214+
215+
License
216+
-------
217+
218+
BSD License
219+
220+
```
221+
Copyright (c) Teracy, Inc. and individual contributors.
222+
All rights reserved.
223+
224+
Redistribution and use in source and binary forms, with or without modification,
225+
are permitted provided that the following conditions are met:
226+
227+
1. Redistributions of source code must retain the above copyright notice,
228+
this list of conditions and the following disclaimer.
229+
230+
2. Redistributions in binary form must reproduce the above copyright
231+
notice, this list of conditions and the following disclaimer in the
232+
documentation and/or other materials provided with the distribution.
233+
234+
3. Neither the name of Teracy, Inc. nor the names of its contributors may be used
235+
to endorse or promote products derived from this software without
236+
specific prior written permission.
237+
238+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
239+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
240+
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
241+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
242+
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
243+
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
244+
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
245+
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
246+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
247+
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
248+
249+
```
250+
251+
[sphinx]: http://sphinx-doc.org

‎doc/makefile

+8-4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
1-
sphinx:
2-
rm -rf build
1+
BUILDDIR = build
2+
3+
html:
4+
rm -rf $(BUILDDIR)
35
rm -rf source/generated
4-
sphinx-build -a source build
5-
cp -R source/_static/images/ build/generated/generated/
6+
sphinx-build -a source $(BUILDDIR)/html
7+
cp -R source/_static/images/ $(BUILDDIR)/html/generated/generated/
8+
9+
include sphinx_deployment.mk

0 commit comments

Comments
 (0)