From 6756df9916f58aa2342b843acbc50a9549f021ed Mon Sep 17 00:00:00 2001 From: Marcin Grzejszczak Date: Tue, 7 Mar 2017 13:24:39 +0100 Subject: [PATCH] Added docs --- README.adoc | 202 +++++++++++ docs/.DS_Store | Bin 0 -> 6148 bytes docs/pom.xml | 41 +++ docs/src/.DS_Store | Bin 0 -> 6148 bytes docs/src/main/.DS_Store | Bin 0 -> 6148 bytes docs/src/main/asciidoc/.DS_Store | Bin 0 -> 6148 bytes docs/src/main/asciidoc/README.adoc | 22 ++ docs/src/main/asciidoc/ghpages.sh | 330 ++++++++++++++++++ .../main/asciidoc/spring-cloud-releaser.adoc | 49 +++ docs/src/main/ruby/generate_readme.sh | 37 ++ pom.xml | 1 + .../cloud/release/ReleaserApplication.java | 2 +- 12 files changed, 683 insertions(+), 1 deletion(-) create mode 100644 README.adoc create mode 100644 docs/.DS_Store create mode 100644 docs/pom.xml create mode 100644 docs/src/.DS_Store create mode 100644 docs/src/main/.DS_Store create mode 100644 docs/src/main/asciidoc/.DS_Store create mode 100644 docs/src/main/asciidoc/README.adoc create mode 100755 docs/src/main/asciidoc/ghpages.sh create mode 100644 docs/src/main/asciidoc/spring-cloud-releaser.adoc create mode 100755 docs/src/main/ruby/generate_readme.sh diff --git a/README.adoc b/README.adoc new file mode 100644 index 00000000..c0a14e47 --- /dev/null +++ b/README.adoc @@ -0,0 +1,202 @@ +// Do not edit this file (e.g. go instead to src/main/asciidoc) + +:jdkversion: 1.8 +:org: marcingrzejszczak +:repo: releaser + +image::https://circleci.com/gh/{org}/{repo}/tree/1.1.x.svg?style=svg["CircleCI", link="https://circleci.com/gh/{org}/{repo}/tree/1.1.x"] +image::https://codecov.io/gh/{org}/{repo}/branch/1.1.x/graph/badge.svg["codecov", link="https://codecov.io/gh/{org}/{repo}"] +image::https://badges.gitter.im/{org}/{repo}.svg[Gitter, link="https://gitter.im/{org}/{repo}?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"] + +:github-tag: master +:org: marcingrzejszczak +:repo: releaser +:github-repo: {org}/{repo} +:github-raw: http://raw.github.com/{github-repo}/{github-tag} +:github-code: http://github.com/{github-repo}/tree/{github-tag} +:toc: left +:toclevels: 8 +:nofooter: + +Spring Cloud Releaser +==================== + +This project can be used to + +- update all versions in your Spring Cloud Project according to the Spring Cloud Release setup + +== How to run it + +Currently we only support running the releaser to update the poms from Java + +[source,bash] +---- +git clone https://github.com/marcingrzejszczak/releaser +cd releaser +./mvnw clean package +---- + +and then go to your project (e.g. Spring Cloud Sleuth) + +[source,bash] +---- +git clone https://github.com/spring-cloud/spring-cloud-sleuth +cd spring-cloud-sleuth +java -jar ~/path/to/cloned/releaser/releaser-spring/target/releaser-spring-0.0.1.BUILD-SNAPSHOT.jar +---- + +You'll be asked to press `Enter` to continue (to check whether you're running it from a proper path). + +== Future plans + +In the future it can also: + +- commit the changed values +- perform a release + +Other plans: + +- add a Maven plugin to perform the work from Maven + +== Building + +:jdkversion: 1.7 + +=== Basic Compile and Test + +To build the source you will need to install 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 + +---- +$ ./mvnw install +---- + +NOTE: You can also install Maven (>=3.3.3) yourself and run the `mvn` command +in place of `./mvnw` in the examples below. If you do that you also +might need to add `-P spring` if your local Maven settings do not +contain repository declarations for spring pre-release artifacts. + +NOTE: Be aware that you might need to increase the amount of memory +available to Maven by setting a `MAVEN_OPTS` environment variable with +a value like `-Xmx512m -XX:MaxPermSize=128m`. We try to cover this in +the `.mvn` configuration, so if you find you have to do it to make a +build succeed, please raise a ticket to get the settings added to +source control. + +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're related to setting git +credentials and you already have those. + +The projects that require middleware generally include a +`docker-compose.yml`, so consider using +http://compose.docker.io/[Docker Compose] to run the middeware servers +in Docker containers. See the README in the +https://github.com/spring-cloud-samples/scripts[scripts demo +repository] for specific instructions about the common cases of mongo, +rabbit and redis. + +NOTE: If all else fails, build with the command from `.travis.yml` (usually +`./mvnw install`). + +=== 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. + +=== 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/[m2eclipse] eclipse plugin for maven support. Other IDEs and tools +should also work without issue as long as they use Maven 3.3.3 or better. + +==== Importing into eclipse with m2eclipse +We recommend the http://eclipse.org/m2e/[m2eclipse] eclipse plugin when working with +eclipse. If you don't already have m2eclipse installed it is available from the "eclipse +marketplace". + +NOTE: Older versions of m2e do not support Maven 3.3, so once the +projects are imported into Eclipse you will also need to tell +m2eclipse to use the right profile for the projects. If you +see many different errors related to the POMs in the projects, check +that you have an up to date installation. If you can't upgrade m2e, +add the "spring" profile to your `settings.xml`. Alternatively you can +copy the repository settings from the "spring" profile of the parent +pom into your `settings.xml`. + +==== Importing into eclipse without m2eclipse +If you prefer not to use m2eclipse you can generate eclipse project metadata using the +following command: + +[indent=0] +---- + $ ./mvnw eclipse:eclipse +---- + +The generated eclipse projects can be imported by selecting `import existing projects` +from the `file` menu. + + +IMPORTANT: There are 2 different versions of language level used in Spring Cloud Sleuth. Java 1.7 is used for main sources and +Java 1.8 is used for tests. When importing your project to an IDE please activate the `ide` Maven profile to turn on +Java 1.8 for both main and test sources. Of course remember that you MUST NOT use Java 1.8 features in the main sources. If you do +so your app will break during the Maven build. + +== Contributing + +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://cla.pivotal.io/sign/spring[Contributor License 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 of Conduct +This project adheres to the Contributor Covenant https://github.com/spring-cloud/spring-cloud-build/blob/master/docs/src/main/asciidoc/code-of-conduct.adoc[code of +conduct]. By participating, you are expected to uphold this code. Please report +unacceptable behavior to spring-code-of-conduct@pivotal.io. + +=== 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://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-dependencies-parent/eclipse-code-formatter.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). \ No newline at end of file diff --git a/docs/.DS_Store b/docs/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..dd9c8cfaf6e2189904ef25c5afeffb45004c49c3 GIT binary patch literal 6148 zcmeHKO^?$s5FKv|+ky~1AT0+Dxgc@qR$YPEy&y%UAoYd_f&-v#(nQ;!Y+U7o0;MQF zWBErMxWm7JH@3TKS~!AOUFs{A&#GyW6H74auW1^!)vmlOT}+W_fG)3O)Ow1U=pkdNjj( zF6j+LG@)XY)chaA=gyixSIFU6;1^R$CzNkQaE0}VUF4T^inw=Zle)Kfy5W5b+4*^N z?tMH_g6NV$+Q&?S$|WjKF$!Uyz}AEBcHZwBc^mM|Xi~3Eyt;KZj8`zvXNI#c!7PdM zqTl}}b{fq~mv>uj$hG!sZz|_r;TL5-@Uxd{6o*k@`p=|H&ij7wJdWn$&W(pME&Mo* zvNiWtFXA+m^MNeWFjsk=_{9{ls?fNzw^-b}d%x=(9WA@g;_$HFbueBo+pWFZ2MfO-CN0ZgDd!qj#=GXFG~}dp1`v5UU^x(m<*Wzv32!gKE8cw%YbFz z4>G{}g9BxB4OSY})`3P{0f0@Im7vcb3>@PabPZM-F#{1g6sSXmxnc+%4!dLgT!WQH z9ZterK7^?(%ne1T>d5aXcM`5f+gb)J19b)(df4If|IzR7|Meg{vJ6-T{woGVbLb5R zSduwgw-(1|tph!VvanyJQH7u}$Fb`0QG64s1al5|fUdzxBP + + 4.0.0 + + org.springframework.cloud + releaser-parent + 0.0.1.BUILD-SNAPSHOT + + releaser-docs + pom + + spring-cloud-releaser + ${basedir}/.. + + + + docs + + + + org.asciidoctor + asciidoctor-maven-plugin + 1.5.3 + false + + + org.apache.maven.plugins + maven-antrun-plugin + false + + + org.codehaus.mojo + build-helper-maven-plugin + false + + + + + + diff --git a/docs/src/.DS_Store b/docs/src/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..402a3c656ae6c72aa1d4a2a0cb0a4cd5fab3f8f2 GIT binary patch literal 6148 zcmeHK%}T>S5Z-O8Hi+1RP>;C?9(rg|Y(a!j>!CLxq6Zb5*kS`|wzR25YbB4NZ{!>J zIQs2RgIc|bNST4zZ+3QOm;E;EW*B3C4}%{L;)rOrvlc(On)=V*rF z+7E?~zMPQc|1%)ZF2{PzV*!i4oZmjiw%?Sfjihn@c-S}R{Nne+U>KLnuRN2@EiJF) zEy$X6>2}4~jlFm@tb2oV)eG7k-`FQYgsJWMr$J|YRoFNbQS1d#XYe8X;w*^TVq6!a zs6ABk9D8vWxoV-SLUA(L-PtSIwc4~~PpZ{&$wq%VwerQS%0aW$yStw}Odp^0QE+^x zO4bd|;2B1`zgu?@g(A9vZx%m`BP0fh0b*bg7%+EResvKxLwg_wh=E^aK;92FRH9=r z(WtHtG^zvu=HONWTmAY2ZRr3y1{00&K)6l?>Qrt@3~nk1uG2B@nD|7aPG?-LjCst; z+*Bys6dv4G;fy;PsU-%8fzJ%c+7D8Y@Bh)y^}hp1b$l@K*wOB5grKr2q+q;AqM`Gfp?IeTEhSU literal 0 HcmV?d00001 diff --git a/docs/src/main/.DS_Store b/docs/src/main/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..e6660dfb56c98b07ead1a403642ed685ff2f3a89 GIT binary patch literal 6148 zcmeHK%}yIJ5FUrLY=o-jPzjE{RN|0BP^*GeRayl&a6?K}4zz;ZY*bd-u2FVF1R-c2 z10I1l;SG2k`i*U(puiPHXl6D3#`cW8{%rY&h*W2oY!EexD1b878c3cIu4kQ-nlGsX zm2D%XgbeleGSi#$mV!lOfaflthzjaaif=l9ab{xF@xu5HU4O6w>ly!eRGfPMyZAIq zi?ZFmSGA@3yZ6gM1M;Eqr+Z>X-7+eNMJE~@+FY9SV{iX7CY#z({44E`j+&pgO8-6vOOH1<+bxa!WYP#$KX3fl zJN|cmF}|E!UE7h6!n(Ec(c>fBz?kFZtUJgvlmA5>$JJ>-LyGB~*ZT}#x2T)t3t16i zKo}4P7K#DC_XR5p^;hyU!hkTa2n_K4prMSR$I7AII*`~W0FbYdR$%j$kz=&S&|~Eg zH4x=Ofi6_}Cx&w2DA(RE^jJA`;iUZIL;0SSf1xPbJKERQomA*hQei+Cc*?+%%QpG^ z-+lT0|1?N)!hkUFrWjE5o$gKtL-J?q+~D}E)zD)o3;R_Lry(%xQ4C)`ir1i4P_Eek Vh8`=2D1pdDz|tUzFz~7j{0Bw$YgPaN literal 0 HcmV?d00001 diff --git a/docs/src/main/asciidoc/.DS_Store b/docs/src/main/asciidoc/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..93a9d46056f38fe8b1f78e66504446df4ffd3a2a GIT binary patch literal 6148 zcmeHK%We}f6uoXkNm5m0fs`(1gTx|5sX(+6LK;H4=mH551PegzOeSPTnvSD+5Vav_ zHvB{R1pb6S;6wNTIM;Sj9u3PXLcWrH{J6*V9KXgyBsxW~Pt+iyDgtArj_4ZWdJapr zVM@4Cs5S~pX+Rl0AaBXr7FY$W0_&y#@7*2xh+XSZPP6+rAW8k>SoZx``taf-;t9h2 z-^!38s?(4{8i6}B`#z&^f%AQVvqce|T`}f;Me|?2{x}<%vHb8yag^ol_D`{~S-G`! zyIO~(nA77^FHK^Z3{lRUI|ZQ)TI}| zRjgkNtX-ViBlN@l4QY@16r;}qJ?^0<#_SdtN4TmzwK6VeRtB24w&n_$RaxC$^KshY zSp}>DH?IJn4-NvOYp~R)jt)fX2>`61SQ*m%qre=;plh(yh#HvCRG_8`^TZIEj&jHN zxduy(nohzzK7{F6m=}sry`z0cxsz};+Sn>!6_{6GQ)e4|{~xV>|Id?b&MIIP_^%WY zm2R)w!6%u!b?M{yu5}Pj5!l$T)Tk(k%yq01d=>8^C_|mY37~7R)QA$8{Si/` +- if the destination switch is passed (-d) then the script will check if the provided dir is a git repo and then will + switch to gh-pages of that repo and copy the generated docs to `docs//` + +USAGE: + +You can use the following options: + +-v|--version - the script will apply the whole procedure for a particular library version +-d|--destination - the root of destination folder where the docs should be copied. You have to use the full path. + E.g. point to spring-cloud-static folder. Can't be used with (-c) +-b|--build - will run the standard build process after checking out the branch +-c|--clone - will automatically clone the spring-cloud-static repo instead of providing the destination. + Obviously can't be used with (-d) + +EOF +} + + +# ========================================== +# ____ ____ _____ _____ _____ _______ +# / ____|/ ____| __ \|_ _| __ \__ __| +# | (___ | | | |__) | | | | |__) | | | +# \___ \| | | _ / | | | ___/ | | +# ____) | |____| | \ \ _| |_| | | | +# |_____/ \_____|_| \_\_____|_| |_| +# +# ========================================== + +while [[ $# > 0 ]] +do +key="$1" +case ${key} in + -v|--version) + VERSION="$2" + shift # past argument + ;; + -d|--destination) + DESTINATION="$2" + shift # past argument + ;; + -b|--build) + BUILD="yes" + ;; + -c|--clone) + CLONE="yes" + ;; + -h|--help) + print_usage + exit 0 + ;; + *) + echo "Invalid option: [$1]" + print_usage + exit 1 + ;; +esac +shift # past argument or value +done + +assert_properties +set_default_props +check_if_anything_to_sync +if [[ -z "${VERSION}" ]] ; then + retrieve_current_branch +else + switch_to_tag +fi +build_docs_if_applicable +retrieve_doc_properties +stash_changes +add_docs_from_target +checkout_previous_branch \ No newline at end of file diff --git a/docs/src/main/asciidoc/spring-cloud-releaser.adoc b/docs/src/main/asciidoc/spring-cloud-releaser.adoc new file mode 100644 index 00000000..1e8f2e7b --- /dev/null +++ b/docs/src/main/asciidoc/spring-cloud-releaser.adoc @@ -0,0 +1,49 @@ +:github-tag: master +:org: marcingrzejszczak +:repo: releaser +:github-repo: {org}/{repo} +:github-raw: http://raw.github.com/{github-repo}/{github-tag} +:github-code: http://github.com/{github-repo}/tree/{github-tag} +:toc: left +:toclevels: 8 +:nofooter: + +Spring Cloud Releaser +==================== + +This project can be used to + +- update all versions in your Spring Cloud Project according to the Spring Cloud Release setup + +== How to run it + +Currently we only support running the releaser to update the poms from Java + +[source,bash] +---- +git clone https://github.com/marcingrzejszczak/releaser +cd releaser +./mvnw clean package +---- + +and then go to your project (e.g. Spring Cloud Sleuth) + +[source,bash] +---- +git clone https://github.com/spring-cloud/spring-cloud-sleuth +cd spring-cloud-sleuth +java -jar ~/path/to/cloned/releaser/releaser-spring/target/releaser-spring-0.0.1.BUILD-SNAPSHOT.jar +---- + +You'll be asked to press `Enter` to continue (to check whether you're running it from a proper path). + +== Future plans + +In the future it can also: + +- commit the changed values +- perform a release + +Other plans: + +- add a Maven plugin to perform the work from Maven \ No newline at end of file diff --git a/docs/src/main/ruby/generate_readme.sh b/docs/src/main/ruby/generate_readme.sh new file mode 100755 index 00000000..6d0ce9dc --- /dev/null +++ b/docs/src/main/ruby/generate_readme.sh @@ -0,0 +1,37 @@ +#!/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 + +# Copied from https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/scripts/asciidoc-coalescer.rb +doc = Asciidoctor.load_file file, safe: :unsafe, header_only: true, attributes: options[:attributes] +header_attr_names = (doc.instance_variable_get :@attributes_modified).to_a +header_attr_names.each {|k| doc.attributes[%(#{k}!)] = '' unless doc.attr? k } +attrs = doc.attributes +attrs['allow-uri-read'] = true +puts attrs + +out = "// Do not edit this file (e.g. go instead to src/main/asciidoc)\n\n" +doc = Asciidoctor.load_file file, safe: :unsafe, parse: false, attributes: attrs +out << doc.reader.read + +unless options[:to_file] + puts out +else + File.open(options[:to_file],'w+') do |file| + file.write(out) + end +end diff --git a/pom.xml b/pom.xml index 2a25239f..e87e13d9 100644 --- a/pom.xml +++ b/pom.xml @@ -17,6 +17,7 @@ + docs releaser-core releaser-spring diff --git a/releaser-spring/src/main/java/org/springframework/cloud/release/ReleaserApplication.java b/releaser-spring/src/main/java/org/springframework/cloud/release/ReleaserApplication.java index 8f3fcbe4..1016acbb 100644 --- a/releaser-spring/src/main/java/org/springframework/cloud/release/ReleaserApplication.java +++ b/releaser-spring/src/main/java/org/springframework/cloud/release/ReleaserApplication.java @@ -41,7 +41,7 @@ public class ReleaserApplication implements CommandLineRunner { @Override public void run(String... strings) throws Exception { String workingDir = System.getProperty("user.dir"); log.info("Will run the application for root folder [{}]", workingDir); - log.info("Press any key to continue..."); + log.info("Press Enter to continue..."); System.in.read(); this.projectUpdater.updateProject(new File(workingDir)); System.exit(0);