Skip to content
This repository was archived by the owner on Dec 12, 2018. It is now read-only.

Commit 28b11bc

Browse files
lhazlewoodlhazlewood
authored
929 zuul docs (#1075)
* save checkpoint * added scms to the guides rendering pipeline * added some excludes to .scms.groovy * testing build for scms installation * testing build for scms installation * fixed file permissions for .sh script * cleaned up exclusion list so sphinx doesn't print warnings * updating scripts to work locally & w/ travis * removed unnecessary block * FINALLY fixed scms discovery issue * formatting cleanup * doc edits cont'd * Added 'forwarded request' page to explain gateway request forwarded data * updated install/render instructions * 929: updated docs per review comments * save checkpoint * added scms to the guides rendering pipeline * added some excludes to .scms.groovy * testing build for scms installation * testing build for scms installation * fixed file permissions for .sh script * cleaned up exclusion list so sphinx doesn't print warnings * updating scripts to work locally & w/ travis * removed unnecessary block * FINALLY fixed scms discovery issue * formatting cleanup * doc edits cont'd * Added 'forwarded request' page to explain gateway request forwarded data * updated install/render instructions * 929: updated docs per review comments
1 parent 0b26b5a commit 28b11bc

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+2110
-1122
lines changed

‎.gitmodules

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
11
[submodule "docs/source/_themes/stormpath"]
22
path = docs/source/_themes/stormpath
33
url = https://github.com/stormpath/stormpath-sphinx-theme.git
4-
[submodule "extensions/spring/boot/docs/source/_themes/stormpath"]
5-
path = extensions/spring/boot/docs/source/_themes/stormpath
6-
url = https://github.com/stormpath/stormpath-sphinx-theme.git

‎ci/before_install.sh

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,10 @@ source ./ci/common.sh
44

55
./ci/travis_bootstrap.sh
66

7-
cp id_rsa_stormpath.github.io ~/.ssh/id_rsa
8-
chmod 600 ~/.ssh/id_rsa
9-
mkdir -p ~/.stormpath/clover
10-
cp clover.license ~/.stormpath/clover
7+
cp id_rsa_stormpath.github.io "$HOME/.ssh/id_rsa"
8+
chmod 600 "$HOME/.ssh/id_rsa"
9+
mkdir -p "$HOME/.stormpath/clover"
10+
cp clover.license "$HOME/.stormpath/clover"
1111
#Using xmllint is faster than invoking maven
1212
export RELEASE_VERSION="$(xmllint --xpath "//*[local-name()='project']/*[local-name()='version']/text()" pom.xml)"
1313
export IS_RELEASE="$([ ${RELEASE_VERSION/SNAPSHOT} == $RELEASE_VERSION ] && [ $TRAVIS_BRANCH == 'master' ] && echo 'true')"

‎ci/build_docs.sh

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,13 @@
22

33
source ./ci/common.sh
44

5-
info "Generating guide docs..."
5+
# Update the path if scms is not available
6+
command -v scms >/dev/null 2>&1 || export PATH="$HOME/usr/local/scms/current/bin:$PATH"
7+
8+
info "Generating guides..."
69
git submodule init
710
git submodule update
8-
(cd docs && make allhtml &> $WORKDIR/target/sphinx.log) &
11+
(cd docs && ./build.sh &> $WORKDIR/target/guides.log) &
912
PID=$!
1013
show_spinner "$PID"
1114

@@ -14,7 +17,7 @@ EXIT_CODE=$?
1417

1518
if [ "$EXIT_CODE" -ne 0 ]; then
1619
error "Error generating guides"
17-
cat $WORKDIR/target/sphinx.log
20+
cat $WORKDIR/target/guides.log
1821
exit $EXIT_CODE
1922
fi
2023

@@ -32,4 +35,3 @@ if [ "$EXIT_CODE" -ne 0 ]; then
3235
cat $WORKDIR/target/javadocs.log
3336
exit $EXIT_CODE
3437
fi
35-

‎ci/install.sh

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,15 @@
33
source ./ci/common.sh
44

55
if [ -n "$BUILD_DOCS" ]; then
6+
info "Installing scms..."
7+
./ci/install_scms.sh $> $WORKDIR/target/install_scms.log
8+
EXIT_CODE=$?
9+
if [ "$EXIT_CODE" -ne 0 ]; then
10+
error "Error installing SCMS"
11+
cat $WORKDIR/target/install_scms.log
12+
exit $EXIT_CODE
13+
fi
14+
615
info "Installing Sphinx..."
716
pip -q install --user sphinx &> $WORKDIR/target/pip.log
817
EXIT_CODE=$?

‎ci/install_aws_cli.sh

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
#! /bin/bash
1+
#! /bin/bash
22

3-
mkdir -p ~/usr/local/aws/bin
3+
mkdir -p "$HOME/usr/local/aws/bin"
44
curl -s "https://s3.amazonaws.com/aws-cli/awscli-bundle.zip" -o "awscli-bundle.zip"
55
unzip awscli-bundle.zip
6-
./awscli-bundle/install -i ~/usr/local/aws -b ~/usr/local/bin/aws
6+
./awscli-bundle/install -i "$HOME/usr/local/aws" -b "$HOME/usr/local/bin/aws"

‎ci/install_scms.sh

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
#!/usr/bin/env bash
2+
3+
SCMS_VERSION="0.3.0"
4+
5+
mkdir -p "$HOME/usr/local/scms"
6+
curl -s "http://repo.maven.apache.org/maven2/com/leshazlewood/scms/scms/$SCMS_VERSION/scms-$SCMS_VERSION.zip" -o scms.zip
7+
unzip scms.zip -d "$HOME/usr/local/scms"
8+
ln -s "$HOME/usr/local/scms/scms-$SCMS_VERSION" "$HOME/usr/local/scms/current"
9+
export PATH="$HOME/usr/local/scms/current/bin:$PATH"

‎ci/publish_coverage_report.sh

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ source ./ci/common.sh
44

55
source ./env.sh
66

7-
export PATH=$PATH:~/usr/local/bin
7+
export PATH="$HOME/usr/local/bin:$PATH"
88

99
info "Publishing coverage results to S3"
1010
aws s3 sync --quiet clover/target/site/clover s3://jsdk-clover-results

‎ci/publish_docs.sh

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,21 @@ git checkout source
1414

1515
info "Copying over servlet plugin docs"
1616
rm -rf source/java/servlet-plugin/
17-
cp -r ../docs/build/html/servlet source/java/servlet-plugin
18-
cp -r ../docs/build/html/servlet source/java/servlet-plugin/latest
19-
cp -r ../docs/build/html/servlet source/java/servlet-plugin/$RELEASE_VERSION
17+
cp -r ../docs/build/servlet/build/html source/java/servlet-plugin
18+
cp -r ../docs/build/servlet/build/html source/java/servlet-plugin/latest
19+
cp -r ../docs/build/servlet/build/html source/java/servlet-plugin/$RELEASE_VERSION
2020

2121
info "Copying over spring boot docs"
2222
rm -rf source/java/spring-boot-web
23-
cp -r ../docs/build/html/springboot source/java/spring-boot-web
24-
cp -r ../docs/build/html/springboot source/java/spring-boot-web/latest
25-
cp -r ../docs/build/html/springboot source/java/spring-boot-web/$RELEASE_VERSION
23+
cp -r ../docs/build/springboot/build/html source/java/spring-boot-web
24+
cp -r ../docs/build/springboot/build/html source/java/spring-boot-web/latest
25+
cp -r ../docs/build/springboot/build/html source/java/spring-boot-web/$RELEASE_VERSION
26+
27+
info "Copying over spring cloud zuul docs"
28+
rm -rf source/java/spring-cloud-zuul
29+
cp -r ../docs/build/sczuul/build/html source/java/spring-cloud-zuul
30+
cp -r ../docs/build/sczuul/build/html source/java/spring-cloud-zuul/latest
31+
cp -r ../docs/build/sczuul/build/html source/java/spring-cloud-zuul/$RELEASE_VERSION
2632

2733
info "Copying over javadocs"
2834
rm -rf source/java/apidocs

‎ci/transfer_logs_to_s3.sh

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ source ./ci/common.sh
44

55
source ./env.sh
66

7-
export PATH=$PATH:~/usr/local/bin
7+
export PATH="$HOME/usr/local/bin:$PATH"
88

99
S3_BASE_BUCKET=s3://jsdk-travis-ci-build-logs
1010
TSTAMP=`date "+%Y-%m-%d_%H-%M-%S"`

‎docs/.scms.groovy

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
def baseExcludes = ['build.sh', 'build/**', 'Makefile', 'readme.md']
2+
3+
//find what version we're on:
4+
def projectVersion = new XmlSlurper().parse(new File("../pom.xml").newReader()).version.text()
5+
6+
scms {
7+
excludes = baseExcludes
8+
9+
model {
10+
apptype = 'application'
11+
port = 8080
12+
maven.project.version = projectVersion
13+
}
14+
15+
model.apptype = 'application'
16+
17+
patterns {
18+
'**/*.rst' {
19+
renderer = 'velocity' //ordinarily only looks for files with vtl extension
20+
outputFileExtension = 'rst' //ordinarily html
21+
}
22+
}
23+
}
24+
25+
environments {
26+
27+
def springExcludes = baseExcludes + ['source/access-control.rst', 'source/appendix/web-stormpath-properties.rst']
28+
29+
servlet {
30+
scms {
31+
excludes = baseExcludes +
32+
//the following files are not relevant for the servlet docs. We exclude them here
33+
//so the sphinx parser doesn't warn us during rendering, e.g.
34+
// WARNING: document isn't included in any toctree
35+
['source/forwarded-request.rst',
36+
'source/about_sczuul.rst',
37+
'source/appendix/default-stormpath-properties.rst',
38+
'source/appendix/spring-boot-core-properties.rst',
39+
'source/appendix/spring-boot-web-properties.rst',
40+
'source/appendix/forgot-password.rst',
41+
'source/appendix/change-password.rst',
42+
'source/appendix/head.rst',
43+
'source/appendix/login.rst',
44+
'source/appendix/register.rst',
45+
'source/appendix/verify.rst']
46+
model {
47+
servlet = true
48+
maven.project.groupId = 'com.stormpath.sdk'
49+
maven.project.artifactId = 'stormpath-servlet-plugin'
50+
}
51+
}
52+
}
53+
54+
sczuul {
55+
scms {
56+
excludes = springExcludes
57+
model {
58+
sczuul = true
59+
apptype = 'gateway'
60+
port = 8000
61+
maven.project.groupId = 'com.stormpath.spring'
62+
maven.project.artifactId = 'stormpath-zuul-spring-cloud-starter'
63+
}
64+
}
65+
}
66+
67+
springboot {
68+
scms {
69+
excludes = springExcludes + ['source/about_sczuul.rst', 'source/forwarded-request.rst']
70+
model {
71+
springboot = true
72+
maven.project.groupId = 'com.stormpath.spring'
73+
maven.project.artifactId = 'stormpath-default-spring-boot-starter'
74+
}
75+
}
76+
}
77+
}

‎docs/Makefile

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ SPHINXBUILD = sphinx-build
77
PAPER =
88
BUILDDIR = build
99
LANGUAGE = servlet
10-
LANGUAGES = servlet springboot
10+
LANGUAGES = servlet springboot sczuul
1111

1212
# User-friendly check for sphinx-build
1313
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
@@ -67,6 +67,12 @@ allhtml:
6767
done
6868
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
6969

70+
sczuulhtml:
71+
@rm -rf $(BUILDDIR)
72+
$(SPHINXBUILD) -n -b html -E $(ALLSPHINXOPTS) -t sczuul $(BUILDDIR)/html/sczuul
73+
@echo
74+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/sczuul"
75+
7076
dirhtml:
7177
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
7278
@echo

‎docs/build.sh

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#!/usr/bin/env bash
2+
3+
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
4+
CWD="$(pwd -P)"
5+
6+
if [ -z "$1" ]; then
7+
targets=( 'servlet' 'springboot' 'sczuul' )
8+
else
9+
targets=( "$1" )
10+
fi
11+
12+
command -v scms >/dev/null 2>&1 || { echo >&2 "The docs/build.sh requires scms to be installed. Aborting."; exit 1; }
13+
command -v sphinx-build >/dev/null 2>&1 || { echo >&2 "The docs/build.sh requires sphinx to be installed. Aborting."; exit 1; }
14+
15+
cd "$SCRIPT_DIR"
16+
17+
for target in "${targets[@]}"; do
18+
scms -e "$target" "$SCRIPT_DIR/build/$target"
19+
cd "$SCRIPT_DIR/build/$target"
20+
sphinx-build -n -b html -E -d build/doctrees source -t "$target" build/html
21+
cd "$SCRIPT_DIR"
22+
done
23+
24+
cd "$CWD"

‎docs/readme.md

Lines changed: 36 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,14 @@
22

33
### Install
44

5+
#### Install SCMS
6+
7+
Download and install SCMS per these instructions: https://github.com/lhazlewood/scms#download-scms
8+
9+
(and yes, ensure `scms` is in your `$PATH`)
10+
11+
#### Install Sphinx
12+
513
`pip install Sphinx sphinx_rtd_theme`
614

715
Other options [here](http://www.sphinx-doc.org/en/stable/install.html).
@@ -12,73 +20,57 @@ If you already have Sphinx, then just upgrade:
1220

1321
**NOTE:** Make sure you are using Sphinx 1.4.6 as a minimum. With previous versions, warnings are treated as errors.
1422

15-
Then clone this repo.
23+
#### Update Stormpath Theme Module
24+
25+
To pick up the shared Stormpath doc theme:
26+
27+
`git submodule update --init --recursive`
1628

1729
### Structure
1830

1931
```
20-
├── source
21-
├── _static
22-
├── _templates
23-
├── images
24-
│   ├── about
25-
│   ├── accnt_mgmt
26-
│   ├── auth_n
27-
│   ├── idsite
28-
│   ├── multitenancy
29-
│   └── quickstart
30-
└── robots
32+
├── source/
33+
├── _static/
34+
├── _themes/
35+
├── appendix/
36+
├── about.rst
37+
├── ... etc ...
38+
└── views.rst
3139
```
3240

3341
- All of the `.rst` files are in `source/`
34-
- All images are in `source/images/`, sorted by chapter name.
3542

3643
### How To Generate The Docs
3744

3845
#### Generating Static Docs
3946

40-
`make html` will generate the Java SDK documentation as HTML.
41-
42-
`make html LANGUAGE={name}` will generate the documentation for the specified language.
43-
44-
The possible values for `{name}` are:
45-
46-
- `servlet`
47-
- `springboot`
48-
49-
If you would like to generate all of the Product Guides in one go, you can use the same command that Travis uses:
47+
In a `bash` shell:
5048

51-
`make allhtml`
52-
53-
This will iterate through every language and generate the Product Guide for that language.
54-
55-
**Note:** This command has an additional `-W` flag that converts all warnings into errors. This means that the build stops at the first warning.
56-
57-
#### Generating Live Docs
58-
59-
In order to generate auto-reloading "live" documentation, you'll need to install sphynx-autobuild:
49+
```
50+
./build.sh
51+
```
6052

61-
`pip install sphinx-autobuild`
53+
This will generate all the integration guides we have.
6254

63-
Then use the following command:
55+
If you want to generate just one guide, you can run:
6456

65-
`make livehtml`
57+
```
58+
./build.sh <name>
59+
```
6660

67-
Just like `make html`, this command can also take a language parameter:
61+
Where `<name>` is the unique identifier of the guide to generate.
6862

69-
`make livehtml LANGUAGE={name}`
63+
The current possible values for `<name>` are:
7064

71-
The values for `{name}` are the same as for generating static documentation.
65+
- `servlet`
66+
- `springboot`
67+
- `sczuul`
7268

7369
### Viewing the Docs
7470

7571
Once you are finished generating the docs, you can view them with the following command:
7672

77-
`open build/html/index.html`
78-
79-
You can replace `index.html` with whatever chapter you would like.
80-
81-
If you used the `make allhtml` command, then you can find the generated files in:
73+
`open build/<name>/build/html/index.html`
8274

83-
`build/html/{language}/index.html`
75+
where, again, `<name>` is one of the above unique identifier names for the guide you want to view.
8476

0 commit comments

Comments
 (0)