add spring cloud documentation infrastructure
fixes gh-5
This commit is contained in:
Spencer Gibb
@@ -7,9 +7,8 @@ before_install:
|
||||
- gem install asciidoctor
|
||||
install:
|
||||
#TODO: build docs
|
||||
- mvn --settings .settings.xml install -U -DskipTests=true -Dmaven.test.redirectTestOutputToFile=true
|
||||
#- mvn --settings .settings.xml install -P docs -q -U -DskipTests=true -Dmaven.test.redirectTestOutputToFile=true
|
||||
#- ./docs/src/main/asciidoc/ghpages.sh
|
||||
- mvn --settings .settings.xml install -P docs -q -U -DskipTests=true -Dmaven.test.redirectTestOutputToFile=true
|
||||
- ./docs/src/main/asciidoc/ghpages.sh
|
||||
script:
|
||||
- '[ "${TRAVIS_PULL_REQUEST}" != "false" ] || mvn --settings .settings.xml deploy -nsu -Dmaven.test.redirectTestOutputToFile=true'
|
||||
- '[ "${TRAVIS_PULL_REQUEST}" = "false" ] || mvn --settings .settings.xml install -nsu -Dmaven.test.redirectTestOutputToFile=true'
|
||||
|
||||
209
README.adoc
Normal file
209
README.adoc
Normal file
@@ -0,0 +1,209 @@
|
||||
// Do not edit this file (e.g. go instead to src/main/asciidoc)
|
||||
|
||||
image::https://travis-ci.org/spring-cloud/spring-cloud-zookeeper.svg?branch=master[Build Status, link=https://travis-ci.org/spring-cloud/spring-cloud-zookeeper]
|
||||
|
||||
This project provides Zookeeper integrations for Spring Boot apps through autoconfiguration
|
||||
and binding to the Spring Environment and other Spring programming model idioms. With a few
|
||||
simple annotations you can quickly enable and configure the common patterns inside your
|
||||
application and build large distributed systems with Zookeeper based components. The
|
||||
patterns provided include Service Discovery, Circuit Breaker and Configuration.
|
||||
Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon) are provided by
|
||||
integration with Spring Cloud Netflix.
|
||||
|
||||
|
||||
== This is a Developer Preview
|
||||
|
||||
We plan on releasing a milestone shortly.
|
||||
|
||||
== Zookeeper overview
|
||||
|
||||
Features of Zookeeper
|
||||
|
||||
* TODO: list high level features of zookeeper
|
||||
|
||||
See the http://zookeeper.apache.org[Zookeeper site] for more information. Spring Cloud Zookeeper also builds on the http://curator.apache.org[Apache Curator] project which started life at Netflix.
|
||||
|
||||
== Spring Cloud Zookeeper Features
|
||||
|
||||
* Spring Cloud `DiscoveryClient` implementation
|
||||
** supports Ribbon and Zuul
|
||||
* Zookeeper based `PropertySource` loaded during the 'bootstrap' phase.
|
||||
|
||||
== Running the sample
|
||||
|
||||
1. TODO: document running the sample
|
||||
|
||||
== Building
|
||||
|
||||
:jdkversion: 1.7
|
||||
|
||||
=== Basic Compile and Test
|
||||
|
||||
To build the source you will need to install
|
||||
http://maven.apache.org/run-maven/index.html[Apache Maven] v3.0.6 or above and JDK {jdkversion}.
|
||||
|
||||
Spring Cloud uses Maven for most build-related activities, and you
|
||||
should be able to get off the ground quite quickly by cloning the
|
||||
project you are interested in and typing
|
||||
|
||||
----
|
||||
$ mvn install -s .settings.xml
|
||||
----
|
||||
|
||||
NOTE: You may need to increase the amount of memory available to Maven by setting
|
||||
a `MAVEN_OPTS` environment variable with the value `-Xmx512m -XX:MaxPermSize=128m`
|
||||
|
||||
The `.settings.xml` is only required the first time (or after updates
|
||||
to dependencies). It is there to provide repository declarations so
|
||||
that those do not need to be hard coded in the project poms.
|
||||
|
||||
For hints on how to build the project look in `.travis.yml` if there
|
||||
is one. There should be a "script" and maybe "install" command. Also
|
||||
look at the "services" section to see if any services need to be
|
||||
running locally (e.g. mongo or rabbit). Ignore the git-related bits
|
||||
that you might find in "before_install" since they will be able git
|
||||
credentials and you already have those.
|
||||
|
||||
If you need mongo, rabbit or redis, see the README in the https://github.com/spring-cloud-samples/scripts[scripts
|
||||
demo repository] for
|
||||
instructions. For example consider using the "fig.yml" with
|
||||
http://www.fig.sh/[Fig] to run them in Docker containers.
|
||||
|
||||
=== Documentation
|
||||
|
||||
The spring-cloud-build module has a "docs" profile, and if you switch
|
||||
that on it will try to build asciidoc sources from
|
||||
`src/main/asciidoc`. As part of that process it will look for a
|
||||
`README.adoc` and process it by loading all the includes, but not
|
||||
parsing or rendering it, just copying it to `${main.basedir}`
|
||||
(defaults to `${basedir}`, i.e. the root of the project). If there are
|
||||
any changes in the README it will then show up after a Maven build as
|
||||
a modified file in the correct place. Just commit it and push the change.
|
||||
|
||||
=== Pull Requests
|
||||
|
||||
Spring Cloud is released under the non-restrictive Apache 2.0 license,
|
||||
and follows a very standard Github development process, using Github
|
||||
tracker for issues and merging pull requests into master. If you want
|
||||
to contribute even something trivial please do not hesitate, but
|
||||
follow the guidelines below.
|
||||
|
||||
==== Sign the Contributor License Agreement
|
||||
Before we accept a non-trivial patch or pull request we will need you
|
||||
to sign the
|
||||
https://support.springsource.com/spring_committer_signup[contributor's
|
||||
agreement]. Signing the contributor's agreement does not grant anyone
|
||||
commit rights to the main repository, but it does mean that we can
|
||||
accept your contributions, and you will get an author credit if we do.
|
||||
Active contributors might be asked to join the core team, and given
|
||||
the ability to merge pull requests.
|
||||
|
||||
==== Code Conventions and Housekeeping
|
||||
None of these is essential for a pull request, but they will all help. They can also be
|
||||
added after the original pull request but before a merge.
|
||||
|
||||
* Use the Spring Framework code format conventions. If you use Eclipse and you follow
|
||||
the ``Importing into eclipse'' instructions below you should get project specific
|
||||
formatting automatically. You can also import formatter settings using the
|
||||
`eclipse-code-formatter.xml` file from the `eclipse` folder. If using IntelliJ, you can
|
||||
use the http://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter Plugin]
|
||||
to import the same file.
|
||||
* Make sure all new `.java` files to have a simple Javadoc class comment with at least an
|
||||
`@author` tag identifying you, and preferably at least a paragraph on what the class is
|
||||
for.
|
||||
* Add the ASF license header comment to all new `.java` files (copy from existing files
|
||||
in the project)
|
||||
* Add yourself as an `@author` to the .java files that you modify substantially (more
|
||||
than cosmetic changes).
|
||||
* Add some Javadocs and, if you change the namespace, some XSD doc elements.
|
||||
* A few unit tests would help a lot as well -- someone has to do it.
|
||||
* If no-one else is using your branch, please rebase it against the current master (or
|
||||
other target branch in the main project).
|
||||
|
||||
=== Working with the code
|
||||
If you don't have an IDE preference we would recommend that you use
|
||||
http://www.springsource.com/developer/sts[Spring Tools Suite] or
|
||||
http://eclipse.org[Eclipse] when working with the code. We use the
|
||||
http://eclipse.org/m2e/[m2eclipe] eclipse plugin for maven support. Other IDEs and tools
|
||||
should also work without issue.
|
||||
|
||||
==== Importing into eclipse with m2eclipse
|
||||
We recommend the http://eclipse.org/m2e/[m2eclipe] eclipse plugin when working with
|
||||
eclipse. If you don't already have m2eclipse installed it is available from the "eclipse
|
||||
marketplace".
|
||||
|
||||
==== Importing into eclipse without m2eclipse
|
||||
If you prefer not to use m2eclipse you can generate eclipse project metadata using the
|
||||
following command:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
$ mvn eclipse:eclipse
|
||||
----
|
||||
|
||||
The generated eclipse projects can be imported by selecting `import existing projects`
|
||||
from the `file` menu.
|
||||
|
||||
==== Adding Project Lombok Agent
|
||||
|
||||
Spring Cloud uses [Project
|
||||
Lombok](http://projectlombok.org/features/index.html) to generate
|
||||
getters and setters etc. Compiling from the command line this
|
||||
shouldn't cause any problems, but in an IDE you need to add an agent
|
||||
to the JVM. Full instructions can be found in the Lombok website. The
|
||||
sign that you need to do this is a lot of compiler errors to do with
|
||||
missing methods and fields, e.g.
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
The method getInitialStatus() is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 120 Java Problem
|
||||
The method getInitialStatus() is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 121 Java Problem
|
||||
The method setNonSecurePort(int) is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 112 Java Problem
|
||||
The type EurekaInstanceConfigBean.IdentifyingDataCenterInfo must implement the inherited abstract method DataCenterInfo.getName() EurekaInstanceConfigBean.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 131 Java Problem
|
||||
The method getId() is undefined for the type ProxyRouteLocator.ProxyRouteSpec PreDecorationFilter.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters/pre line 60 Java Problem
|
||||
The method getLocation() is undefined for the type ProxyRouteLocator.ProxyRouteSpec PreDecorationFilter.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters/pre line 55 Java Problem
|
||||
----
|
||||
|
||||
==== Importing into other IDEs
|
||||
Maven is well supported by most Java IDEs. Refer to you vendor documentation.
|
||||
|
||||
|
||||
== Contributing
|
||||
|
||||
Spring Cloud is released under the non-restrictive Apache 2.0 license. If you would like
|
||||
to contribute something, or simply want to hack on the code this document should help
|
||||
you get started.
|
||||
|
||||
=== Sign the Contributor License Agreement
|
||||
Before we accept a non-trivial patch or pull request we will need you to sign the
|
||||
https://support.springsource.com/spring_committer_signup[contributor's agreement].
|
||||
Signing the contributor's agreement does not grant anyone commit rights to the main
|
||||
repository, but it does mean that we can accept your contributions, and you will get an
|
||||
author credit if we do. Active contributors might be asked to join the core team, and
|
||||
given the ability to merge pull requests.
|
||||
|
||||
=== Code Conventions and Housekeeping
|
||||
None of these is essential for a pull request, but they will all help. They can also be
|
||||
added after the original pull request but before a merge.
|
||||
|
||||
* Use the Spring Framework code format conventions. If you use Eclipse
|
||||
you can import formatter settings using the
|
||||
`eclipse-code-formatter.xml` file from the
|
||||
https://github.com/spring-cloud/build/tree/master/eclipse-coding-conventions.xml[Spring
|
||||
Cloud Build] project. If using IntelliJ, you can use the
|
||||
http://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter
|
||||
Plugin] to import the same file.
|
||||
* Make sure all new `.java` files to have a simple Javadoc class comment with at least an
|
||||
`@author` tag identifying you, and preferably at least a paragraph on what the class is
|
||||
for.
|
||||
* Add the ASF license header comment to all new `.java` files (copy from existing files
|
||||
in the project)
|
||||
* Add yourself as an `@author` to the .java files that you modify substantially (more
|
||||
than cosmetic changes).
|
||||
* Add some Javadocs and, if you change the namespace, some XSD doc elements.
|
||||
* A few unit tests would help a lot as well -- someone has to do it.
|
||||
* If no-one else is using your branch, please rebase it against the current master (or
|
||||
other target branch in the main project).
|
||||
* When writing a commit message please follow http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[these conventions],
|
||||
if you are fixing an existing issue please add `Fixes gh-XXXX` at the end of the commit
|
||||
message (where XXXX is the issue number).
|
||||
17
README.md
17
README.md
@@ -1,17 +0,0 @@
|
||||
spring-cloud-zookeeper
|
||||
===================
|
||||
|
||||
[](https://travis-ci.org/spring-cloud/spring-cloud-zookeeper)
|
||||
|
||||
Developer Preview
|
||||
|
||||
### TODO
|
||||
|
||||
- [X] zookeeper config
|
||||
- [X] zookeeper service discovery
|
||||
- [X] zookeeper ribbon load balancer
|
||||
- [ ] zookeeper ui
|
||||
- [X] zookeeper property source
|
||||
- [ ] zookeeper event bus
|
||||
- [ ] send messages
|
||||
- [ ] receive messages
|
||||
45
docs/pom.xml
Normal file
45
docs/pom.xml
Normal file
@@ -0,0 +1,45 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
<parent>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-build</artifactId>
|
||||
<version>1.0.2.BUILD-SNAPSHOT</version>
|
||||
<relativePath/>
|
||||
</parent>
|
||||
<artifactId>spring-cloud-zookeeper-docs</artifactId>
|
||||
<packaging>pom</packaging>
|
||||
<name>Spring Cloud Zookeeper Docs</name>
|
||||
<description>Spring Cloud Docs</description>
|
||||
<version>1.0.0.BUILD-SNAPSHOT</version>
|
||||
<properties>
|
||||
<docs.main>spring-cloud-zookeeper</docs.main>
|
||||
<main.basedir>${basedir}/..</main.basedir>
|
||||
</properties>
|
||||
<profiles>
|
||||
<profile>
|
||||
<id>docs</id>
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.asciidoctor</groupId>
|
||||
<artifactId>asciidoctor-maven-plugin</artifactId>
|
||||
<inherited>false</inherited>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-antrun-plugin</artifactId>
|
||||
<inherited>false</inherited>
|
||||
</plugin>
|
||||
<plugin>
|
||||
<groupId>org.codehaus.mojo</groupId>
|
||||
<artifactId>build-helper-maven-plugin</artifactId>
|
||||
<inherited>false</inherited>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
</profile>
|
||||
</profiles>
|
||||
</project>
|
||||
33
docs/src/main/asciidoc/README.adoc
Normal file
33
docs/src/main/asciidoc/README.adoc
Normal file
@@ -0,0 +1,33 @@
|
||||
image::https://travis-ci.org/spring-cloud/spring-cloud-zookeeper.svg?branch=master[Build Status, link=https://travis-ci.org/spring-cloud/spring-cloud-zookeeper]
|
||||
|
||||
include::intro.adoc[]
|
||||
|
||||
== This is a Developer Preview
|
||||
|
||||
We plan on releasing a milestone shortly.
|
||||
|
||||
== Zookeeper overview
|
||||
|
||||
Features of Zookeeper
|
||||
|
||||
* TODO: list high level features of zookeeper
|
||||
|
||||
See the http://zookeeper.apache.org[Zookeeper site] for more information. Spring Cloud Zookeeper also builds on the http://curator.apache.org[Apache Curator] project which started life at Netflix.
|
||||
|
||||
== Spring Cloud Zookeeper Features
|
||||
|
||||
* Spring Cloud `DiscoveryClient` implementation
|
||||
** supports Ribbon and Zuul
|
||||
* Zookeeper based `PropertySource` loaded during the 'bootstrap' phase.
|
||||
|
||||
== Running the sample
|
||||
|
||||
1. TODO: document running the sample
|
||||
|
||||
== Building
|
||||
|
||||
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/building.adoc[]
|
||||
|
||||
== Contributing
|
||||
|
||||
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing.adoc[]
|
||||
46
docs/src/main/asciidoc/ghpages.sh
Executable file
46
docs/src/main/asciidoc/ghpages.sh
Executable file
@@ -0,0 +1,46 @@
|
||||
#!/bin/bash -x
|
||||
|
||||
git remote set-url --push origin `git config remote.origin.url | sed -e 's/^git:/https:/'`
|
||||
|
||||
if ! (git remote set-branches --add origin gh-pages && git fetch -q); then
|
||||
echo "No gh-pages, so not syncing"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if ! [ -d docs/target/generated-docs ]; then
|
||||
echo "No gh-pages sources in docs/target/generated-docs, so not syncing"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Stash any outstanding changes
|
||||
###################################################################
|
||||
git diff-index --quiet HEAD
|
||||
dirty=$?
|
||||
if [ "$dirty" != "0" ]; then git stash; fi
|
||||
|
||||
# Switch to gh-pages branch to sync it with master
|
||||
###################################################################
|
||||
git checkout gh-pages
|
||||
|
||||
for f in docs/target/generated-docs/*; do
|
||||
file=${f#docs/target/generated-docs/*}
|
||||
if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then
|
||||
# Not ignored...
|
||||
cp -rf $f .
|
||||
git add -A $file
|
||||
fi
|
||||
done
|
||||
|
||||
git commit -a -m "Sync docs from master to gh-pages"
|
||||
|
||||
# Uncomment the following push if you want to auto push to
|
||||
# the gh-pages branch whenever you commit to master locally.
|
||||
# This is a little extreme. Use with care!
|
||||
###################################################################
|
||||
git push origin gh-pages
|
||||
|
||||
# Finally, switch back to the master branch and exit block
|
||||
git checkout master
|
||||
if [ "$dirty" != "0" ]; then git stash pop; fi
|
||||
|
||||
exit 0
|
||||
0
docs/src/main/asciidoc/images/.gitkeep
Normal file
0
docs/src/main/asciidoc/images/.gitkeep
Normal file
8
docs/src/main/asciidoc/intro.adoc
Normal file
8
docs/src/main/asciidoc/intro.adoc
Normal file
@@ -0,0 +1,8 @@
|
||||
This project provides Zookeeper integrations for Spring Boot apps through autoconfiguration
|
||||
and binding to the Spring Environment and other Spring programming model idioms. With a few
|
||||
simple annotations you can quickly enable and configure the common patterns inside your
|
||||
application and build large distributed systems with Zookeeper based components. The
|
||||
patterns provided include Service Discovery, Circuit Breaker and Configuration.
|
||||
Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon) are provided by
|
||||
integration with Spring Cloud Netflix.
|
||||
|
||||
21
docs/src/main/asciidoc/spring-cloud-zookeeper.adoc
Normal file
21
docs/src/main/asciidoc/spring-cloud-zookeeper.adoc
Normal file
@@ -0,0 +1,21 @@
|
||||
:github-tag: master
|
||||
:github-repo: spring-cloud/spring-cloud-zookeeper
|
||||
:github-raw: http://raw.github.com/{github-repo}/{github-tag}
|
||||
:github-code: http://github.com/{github-repo}/tree/{github-tag}
|
||||
= Spring Cloud Zookeeper
|
||||
|
||||
include::intro.adoc[]
|
||||
|
||||
[[spring-cloud-zookeeper-install]]
|
||||
== Install Zookeeper
|
||||
TODO: document zookeeper installation
|
||||
|
||||
[[spring-cloud-zookeeper-discovery]]
|
||||
== Service Discovery with Zookeeper
|
||||
|
||||
TODO: document zookeeper service discovery
|
||||
|
||||
[[spring-cloud-zookeeper-config]]
|
||||
== Distributed Configuration with Zookeeper
|
||||
|
||||
TODO: document zookeeper config
|
||||
30
docs/src/main/ruby/generate_readme.sh
Executable file
30
docs/src/main/ruby/generate_readme.sh
Executable file
@@ -0,0 +1,30 @@
|
||||
#!/usr/bin/env ruby
|
||||
|
||||
base_dir = File.join(File.dirname(__FILE__),'../../..')
|
||||
src_dir = File.join(base_dir, "/src/main/asciidoc")
|
||||
require 'asciidoctor'
|
||||
require 'optparse'
|
||||
|
||||
options = {}
|
||||
file = "#{src_dir}/README.adoc"
|
||||
|
||||
OptionParser.new do |o|
|
||||
o.on('-o OUTPUT_FILE', 'Output file (default is stdout)') { |file| options[:to_file] = file unless file=='-' }
|
||||
o.on('-h', '--help') { puts o; exit }
|
||||
o.parse!
|
||||
end
|
||||
|
||||
file = ARGV[0] if ARGV.length>0
|
||||
|
||||
srcDir = File.dirname(file)
|
||||
out = "// Do not edit this file (e.g. go instead to src/main/asciidoc)\n\n"
|
||||
doc = Asciidoctor.load_file file, safe: :safe, parse: false, attributes: 'allow-uri-read'
|
||||
out << doc.reader.read
|
||||
|
||||
unless options[:to_file]
|
||||
puts out
|
||||
else
|
||||
File.open(options[:to_file],'w+') do |file|
|
||||
file.write(out)
|
||||
end
|
||||
end
|
||||
Reference in New Issue
Block a user