Author: bobby
Date: Fri Mar 25 21:26:21 2016
New Revision: 1736665
URL: http://svn.apache.org/viewvc?rev=1736665&view=rev
Log:
Updated README with more details about the plugin, and updated the plugin to
match what is in git.
Modified:
storm/site/README.md
storm/site/_plugins/releases.rb
Modified: storm/site/README.md
URL:
http://svn.apache.org/viewvc/storm/site/README.md?rev=1736665&r1=1736664&r2=1736665&view=diff
==============================================================================
--- storm/site/README.md (original)
+++ storm/site/README.md Fri Mar 25 21:26:21 2016
@@ -1,5 +1,16 @@
# Apache Storm Website and Documentation
-This is the source for the Storm website and documentation. It is statically
generated using [jekyll](http://jekyllrb.com).
+This is the source for the Release specific part of the Apache Storm website
and documentation. It is statically generated using
[jekyll](http://jekyllrb.com).
+
+## Generate Javadoc
+
+You have to generate javadoc on project root before generating document site.
+
+```
+mvn javadoc:javadoc
+mvn javadoc:aggregate -DreportOutputDirectory=./docs/ -DdestDir=javadocs
+```
+
+You need to create distribution package with gpg certificate. Please refer
[here](https://github.com/apache/storm/blob/master/DEVELOPER.md#packaging).
## Site Generation
First install jekyll (assuming you have ruby installed):
@@ -20,18 +31,81 @@ Point your browser to http://localhost:4
By default, jekyll will generate the site in a `_site` directory.
+This will only show the portion of the documentation that is specific to this
release.
-## Publishing the Website
-In order to publish the website, you must have committer access to Storm's
subversion repository.
-
-The Storm website is published using Apache svnpubsub. Any changes committed
to subversion will be automatically published to storm.apache.org.
+## Adding a new release to the website
+In order to add a new relase, you must have committer access to Storm's
subversion repository at https://svn.apache.org/repos/asf/storm/site.
-To publish changes, tell jekyll to generate the site in the `publish`
directory of subversion, then commit the changes:
+Release documentation is placed under the releases directory named after the
release version. Most metadata about the release will be generated
automatically from the name using a jekyll plugin. Or by plaing them in the
_data/releases.yml file.
+To create a new release run the following from the main git directory
```
+mvn javadoc:javadoc
+mvn javadoc:aggregate -DreportOutputDirectory=./docs/ -DdestDir=javadocs
cd docs
-jekyll build -d /path/to/svn/repo/publish
-cd /path/to/svn/repo/publish
+mkdir ${path_to_svn}/releases/${release_name}
+cp -r *.md images/ javadocs/ ${path_to_svn}/releases/${release_name}
+cd ${path_to_svn}
+svn add releases/${release_name}
+svn commit
+```
+
+to publish a new release run
+
+```
+cd ${path_to_svn}
+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)
+```
Modified: storm/site/_plugins/releases.rb
URL:
http://svn.apache.org/viewvc/storm/site/_plugins/releases.rb?rev=1736665&r1=1736664&r2=1736665&view=diff
==============================================================================
--- storm/site/_plugins/releases.rb (original)
+++ storm/site/_plugins/releases.rb Fri Mar 25 21:26:21 2016
@@ -20,7 +20,29 @@ module Releases
return version_string.split('.').map{|e| e.to_i}
end
+ def release_from_pom()
+ text= `mvn -f ../pom.xml help:evaluate -Dexpression=project.version`
+ return text.split("\n").select{|a| !a.start_with?('[')}[0]
+ end
+
+ def branch_from_git()
+ return `git rev-parse --abbrev-ref HEAD`
+ end
+
def generate(site)
+ if site.config['storm_release_only']
+ release_name = release_from_pom()
+ puts "release: #{release_name}"
+ git_branch = branch_from_git()
+ puts "branch: #{git_branch}"
+ for page in site.pages do
+ page.data['version'] = release_name;
+ page.data['git-tree-base'] =
"http://github.com/apache/storm/tree/#{git_branch}";
+ page.data['git-blob-base'] =
"http://github.com/apache/storm/blob/#{git_branch}";
+ end
+ return
+ end
+
releases = Hash.new
if (site.data['releases'])
for rel_data in site.data['releases'] do
