aurora-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From wfar...@apache.org
Subject svn commit: r1720052 - /aurora/site/README.md
Date Tue, 15 Dec 2015 00:19:38 GMT
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 



Mime
View raw message