Repository: storm Updated Branches: refs/heads/0.10.x-branch ed7bcebb0 -> 2322cca3a
Clarified docs. Project: http://git-wip-us.apache.org/repos/asf/storm/repo Commit: http://git-wip-us.apache.org/repos/asf/storm/commit/2322cca3 Tree: http://git-wip-us.apache.org/repos/asf/storm/tree/2322cca3 Diff: http://git-wip-us.apache.org/repos/asf/storm/diff/2322cca3 Branch: refs/heads/0.10.x-branch Commit: 2322cca3a754719e7522a1f3cc2f30c6ac9882d5 Parents: ed7bceb Author: Robert (Bobby) Evans <[email protected]> Authored: Fri Mar 25 16:20:33 2016 -0500 Committer: Robert (Bobby) Evans <[email protected]> Committed: Fri Mar 25 16:23:28 2016 -0500 ---------------------------------------------------------------------- docs/README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/storm/blob/2322cca3/docs/README.md ---------------------------------------------------------------------- diff --git a/docs/README.md b/docs/README.md index b26d3ff..49ad248 100644 --- a/docs/README.md +++ b/docs/README.md @@ -59,3 +59,53 @@ jekyll build -d publish/ svn add publish/ #Add any new files svn commit ``` + +## How release specific docs work + +Release specific documentation is controlled by a jekyll plugin [releases.rb](./_plugins/releases.rb) + +If the plugin is running from the git repo the config `storm_release_only` is set and teh plugin will treat all of the markdown files as release sepcific file. + +If it is running from the subversion repositiory it will look in the releases driectory for release sepcific docs. + +http://svn.apache.org/viewvc/storm/site/releases/ + +Each sub directory named after the release in question. The "current" release is pointed to by a symlink in that directory called `current`. + +The plugin sets three configs for each release page. + + * version - the version number of the release/directory + * git-tree-base - a link to a directory in github that this version is on + * git-blob-base - a link to to where on github that this version is on, but should be used when pointing to files. + +If `storm_release_only` is set for the project the version is determined from the maven pom.xml and the branch is the current branch in git. If it is not set the version is determined by the name of the sub-directory and branch is assumed to be a `"v#{version}"` which corresponds with our naming conventions. For SNAPSHOT releases you will need to override this in `_data/releases.yml` + +The plugin also augments the `site.data.releases` dataset. +Each release in the list includes the following, and each can be set in `_data/releases.yml` to override what is automatically generated by the plugin. + + * git-tag-or-branch - tag or branch name on github/apache/storm + * git-tree-base - a link to a directory in github that this version is on + * git-blob-base - a link to to where on github that this version is on, but should be used when pointing to files. + * base-name - name of the release files to download, without the .tar.gz + * has-download - if this is an official release and a download link should be created. + +So if you wanted to create a link to a file on github inside the release specific docs you would create a link like + +``` +[LICENSE]([DEVELOPER.md]({{page.git-blob-base}}/LICENSE) +``` + +If you wanted to create a maven string to tell people what dependency to use you would do something like + +``` +<dependency> + ... + <version>{{version}}</version> +</dependency> +``` + +If you want to refer to a javadoc for the current release use a relative path. It will be in the javadocs subdirectory. + +``` +[TopologyBuilder](javadocs/org/apache/storm/topology/TopologyBuilder.html) +```
