Author: wfarner
Date: Tue Dec 15 00:19:37 2015
New Revision: 1720052
URL: http://svn.apache.org/viewvc?rev=1720052&view=rev
Log:
Add more thorough documentation for generating website docs.
Modified:
aurora/site/README.md
Modified: aurora/site/README.md
URL:
http://svn.apache.org/viewvc/aurora/site/README.md?rev=1720052&r1=1720051&r2=1720052&view=diff
==============================================================================
--- aurora/site/README.md (original)
+++ aurora/site/README.md Tue Dec 15 00:19:37 2015
@@ -52,11 +52,55 @@ other files within the source folder.
### Other available tasks
- rake2.0 build # Build the website from source
- rake2.0 clean # Remove any temporary products
- rake2.0 clobber # Remove any generated file
- rake2.0 dev # Run the site in development mode
- rake2.0 update_docs # Update the latest docs from the Apache Aurora
codebase
+ rake2.0 build # Build the website from source
+ rake2.0 clean # Remove any temporary products
+ rake2.0 clobber # Remove any generated file
+ rake2.0 dev # Run the site in development mode
+ rake2.0 generate_docs # Fetch documentation from git for rendering.
+
+### Generating documentation pages from git
+The majority of our documentation currently lives in git as markdown. The
`generate_docs`
+task automates the process of fetching the markdown, performing some
translations, and
+storing it in a version-specific directory under `source/documentation`.
+
+First, prepare the vagrant environment and move into the `/vagrant` directory:
+
+ $ vagrant up
+ $ vagrant ssh
+ vagrant@vagrant-ubuntu-trusty-64:~$ cd /vagrant
+
+You will use the `generate_docs` rake task to fetch the docs you wish to place
on the website.
+This task takes two arguments - `title` and `git_tag`. The title is the name
to give this branch
+of documentation. All titles should be a release and must be listed in
`data/downloads.yml`,
+with the exception of the `latest` title. Each title will be represented as a
directory under
+`source/documentation`.
+
+#### Updating documentation to match git master
+If a documentation patch is contributed and you would like to update the
website to reflect
+it, you will be updating the documentation for `latest`.
+Note: since documentation is associated with versions, be careful to avoid
publishing
+misleading documentation for unreleased featuresl
+
+ # This will fetch the docs and place them in `source/documentation/latest`.
+ rake2.0 generate_docs[latest,master]
+
+ # Render the docs.
+ rake2.0
+
+#### Updating the documentation for a release.
+After completing an official Aurora release, you should add the new version of
documentation and
+advertise the release on the website.
+
+First, add the new release to the top of `data/downloads.yml`.
+
+ # Add documentation for the new release
+ rake2.0 generate_docs[$RELEASE,$RELEASE]
+
+ # Update the `latest` release docs
+ rake2.0 generate_docs[latest,$RELEASE]
+
+ # Render the docs.
+ rake2.0
### Development
To live edit the site run `rake2.0 dev` and then open a browser window to
