Adds maintains docs section to README

.rvmrc

@@ -12,7 +12,7 @@ rvm_gemset_create_on_use_flag=1
 # First we specify our desired <ruby>[@<gemset>], the @gemset name is optional,
 # Only full ruby name is supported here, for short names use:
 #     echo "rvm use 1.9.3" > .rvmrc
-environment_id="ruby-1.9.3-p194@jekyll"
+environment_id="ruby-1.9.3@jekyll"
 
 
 # First we attempt to load the desired environment directly from the environment

README.md

@@ -12,48 +12,54 @@ files Jekyll.
 Our docs will be transformed into readable pages using Jekyll. Jekyll
 allows us to write our documentation in markdown, and host it as
 static pages in github. We are particularly using
-jekyll-bootstrap. Learn more about jekyll-bootstrap at
-http://www.jekyllbootstrap.com
+jekyll-bootstrap. [Learn more about jekyll-bootstrap.](http://www.jekyllbootstrap.com)
+
 
 ## Creating and editing documentation
+You can write everything in markdown (see markdown_styleguide.md for more
+information.) and do code highlighting inline with backticks `code` or
+in blocks with the template:
+
+    {% highlight java %}
+    block of code goes here
+    {% endhighlight %}
+
+Java in the above template can be any short name for a language from
+[this list.](http://pygments.org/languages/) 
+
 To add a new file, find the user guide section or article you want and
 create a file named YYYY-MM-DD-title.md under the _posts directory,
 and write it using markdown syntax. In the file, you should include
 the following at the top of the file (include the dashes):
 
     ---
     layout: post
-    title: My Content Title
-    category: [userguide, schema, 1.0.0-rc1] or tutorial
-    tags: [doc_type]
-    description: A tutorial on computer stuff.
+    title: Delete Contacts
+    categories: [tutorials, phonebook-tutorial, 1.0.0-rc4]
+    tags: [article]
+    order: 8
+    description: Examples of Point deletions.
     ---
 
 The above is YAML Front Matter syntax that instructs Jekyll what to do
-with the file when compiling it into a static site. Set the 'doc_type'
-is either 'article' or 'schema_ug'. The tag allows us to collate
-articles and userguides. The ordering of these articles and userguides
-is determined by the date in the filename. Janky, c'est la vie.
-You can write everything in markdown (see markdown_styleguide.md for more
-information.) and do code highlighting inline with backticks `code` or
-in blocks with the template:
+with the file when compiling it into a static site. The tag allows us to collate
+articles and userguides.
 
-    {% highlight java %}
-    block of code goes here
-    {% endhighlight %}
-
-Java in the above template can be any short name for a language from
-[this list.](http://pygments.org/languages/) 
 
 ## Previewing Changes
-
 In order to preview what your changes look like, you will need to have
 Ruby and Jekyll installed. It is highly recommended that you control your
 ruby version using rvm. Check out instructions at
-http://github.com/mojombo/jekyll. Once Jekyll is installed `jekyll
---server --safe` will display the site corresponding to the
-current state of the project at http://localhost:4000. Note that the
-pygments highlighting of codeblocks will only work if you have
+http://github.com/mojombo/jekyll.
+
+
+To see how your local version of kiji-docs renders, run `rake preview`. This
+command turns off google analytics, so as not to inflate our stats, and runs 
+`jekyll --no-auto --server --pygments --no-lsi --safe`. Since we use the no-auto
+parameter, you will need to rerun preview to see new changes, but trust us,
+it is better this way.
+
+Note that the pygments highlighting of codeblocks will only work if you have
 pygments installed.
 
 ## Contributing Documentation
@@ -66,3 +72,25 @@ pygments installed.
 * Reference the jira in the commit message (e.g., "DOCS-1: Subscribe buttons to the mailing lists on the website are broken")
 * Push your branch: git push origin my_fix.
 * Use [pull requests](https://help.github.com/articles/using-pull-requests) to contribute your changes once you are done.
+
+## Maintaing Docs
+
+
+In order to maintain the docs repo, you need to know:
+* How Jekyll works. We use a particular framework called [Jekyll Bootstrap](http://jekyllbootstrap.com/)
+  Their docs are great, so use them. 
+* How we use front matter on posts. The most important(/hackiest uses) labels and their uses are:
+  ** categories : This defines the prefix of a url. For example a post with categories = [a, b, c] and
+     file name 2012-01-01-title, will have the full url of {{ site.BASE_URL }}/a/b/c/title.
+  ** order : Putting sections of the userguide in the correct order is tricky, and done in a very
+     silly way. See _includes/themes/twitter/post.html and _includes/side-toc.html for examples of
+     where the order label is used. Jekyll is not made for our use case, so we have some hilarious
+     ways of bending its behavior to our will. In the long run, the way we generate the side-toc is
+     going to slow down the generation of the site considerably. This is one reason that the current
+     Jekyll based docs site is going to need to be replaced with something more resilient in the future.
+* The directory structure inside of the _posts doesn't affect the urls that get generated for posts,
+  but we make it match the urls as much as possible. Specificly, that means that if the overview
+  section of a userguide has the categories tag [userguides, schema, 1.0.0-rc4], then the markdown
+  file should be located in _posts/userguides/schema/1.0.0-rc4. This is just a convention that helps
+  with organization and navigation.
+* Sometimes weird errors happen, adding whitespace will help, about half of the time.

Rakefile

@@ -97,7 +97,7 @@ end # task :page
 
 desc "Launch preview environment"
 task :preview do
-  system "jekyll --auto --server"
+  system "./scripts/run-server.sh"
 end # task :preview
 
 # Public: Alias - Maintains backwards compatability for theme switching.

_config.yml

@@ -12,10 +12,9 @@ pygments: true
 title : Kiji Community
 author :
   name : WibiData
-  email : blah@email.test
-  github : username
-  twitter : username
-  feedburner : feedname
+  email : admin@wibidata.com
+  github : kijiproject
+  twitter : kijiproject
 
 # URL of the kiji site.
 #
@@ -30,9 +29,31 @@ kiji_url : http://www.kiji.org
 # Finally if you are pushing to a GitHub project page, include the project name at the end.
 #
 production_url : http://docs.kiji.org
-userguide_url : /userguide/schema/1.0.0-rc1/
-tutorial_url : /tutorial/
-api_url : /apidocs/org/kiji/schema/
+api_url : /apidocs
+userguide_url : /userguides
+tutorial_url : /tutorials
+
+# rc1
+api_schema_rc1 : /apidocs/kiji-schema/1.0.0-rc1/org/kiji/schema
+userguide_schema_rc1 : /userguides/schema/1.0.0-rc1
+
+# rc2
+api_schema_rc2 : /apidocs/kiji-schema/1.0.0-rc2/org/kiji/schema
+userguide_schema_rc2 : /userguides/schema/1.0.0-rc2
+
+# rc3
+api_schema_rc3 : /apidocs/kiji-schema/1.0.0-rc3/org/kiji/schema
+tutorial_phonebook_rc3 : /tutorials/phonebook-tutorial/1.0.0-rc3
+userguide_schema_rc3 : /userguides/schema/1.0.0-rc3
+
+# rc4
+api_schema_rc4 : /apidocs/kiji-schema/1.0.0-rc4/org/kiji/schema
+api_mr_rc4 : /apidocs/kiji-mapreduce/1.0.0-rc4/org/kiji/mapreduce
+api_mrlib_rc4 : /apidocs/kiji-mapreduce-lib/1.0.0-rc4/org/kiji/mapreduce
+tutorial_phonebook_rc4 : /tutorials/phonebook-tutorial/1.0.0-rc4
+tutorial_music_rc4 : /tutorials/music-recommendation/1.0.0-rc4
+userguide_schema_rc4 : /userguides/schema/1.0.0-rc4
+userguide_mapreduce_rc4 : /userguides/mapreduce/1.0.0-rc4
 
 # All Jekyll-Bootstrap specific configurations are namespaced into this hash
 #
@@ -84,19 +105,19 @@ JB :
   # Set 'provider' to the comment provider you want to use.
   # Set 'provider' to false to turn commenting off globally.
   #
-  comments :
-    provider : disqus
-    disqus :
-      short_name : jekyllbootstrap
-    livefyre :
-      site_id : 123
-    intensedebate :
-      account : 123abc
-    facebook :
-      appid : 123
-      num_posts: 5
-      width: 580
-      colorscheme: light
+  #comments :
+  #  provider : disqus
+  #  disqus :
+  #    short_name : jekyllbootstrap
+  #  livefyre :
+  #    site_id : 123
+  #  intensedebate :
+  #    account : 123abc
+  #  facebook :
+  #    appid : 123
+  #    num_posts: 5
+  #    width: 580
+  #    colorscheme: light
 
   # Settings for analytics helper
   # Set 'provider' to the analytics provider you want to use.

_includes/side-toc.html

@@ -6,16 +6,27 @@ <h3>{{ title }}</h3>
           {% assign index = forloop.index %}
           {% for subpage in pages %}
             {% if index == subpage.order %}
-              <li>
-                {% if subpage.url == page.url %}
-                  <b>{{ subpage.title }}</b>
-                {% else %}
-                  <a href="{{ BASE_PATH }}{{ subpage.url }}">{{ subpage.title }}</a>
-                {% endif %}
-              </li>
+              {% if subpage.categories == page.categories %}
+                <li>
+                  {% if subpage.url == page.url %}
+                    <b>{{ subpage.title }}</b>
+                  {% else %}
+                    <a href="{{ BASE_PATH }}{{ subpage.url }}">{{ subpage.title }}</a>
+                  {% endif %}
+                </li>
+              {% endif %}
             {% endif %}
           {% endfor %}
         {% endfor %}
       </ul>
+      <h3>Need Help?</h3>
+      <ul>
+        <li>
+      <a class="btn btn-info"  href="https://groups.google.com/a/kiji.org/forum/?fromgroups#!forum/user">User Group Mailing List</a>
+        </li>
+        <li>
+      <a class="btn btn-warning" href="https://jira.kiji.org/secure/CreateIssueDetails!init.jspa?pid=10004&issuetype=1&priority=3&components=10010&summary=Reported%20Docs%20Error:%20{{ page.title }}&description=Please%20describe%20the%20issue.%0a%0aurl:%20{{ page.url }}"> Report an Error in Docs </a> 
+        </li>
+    </ul>
     </div>
 </div>

_includes/themes/twitter/default.html

@@ -8,6 +8,9 @@
     <link href="{{ ASSET_PATH }}/bootstrap/css/bootstrap.min.css" rel="stylesheet">
     <link href="{{ ASSET_PATH }}/css/style.css" rel="stylesheet" type="text/css" media="all">
     <link href="{{ ASSET_PATH }}/css/github.css" rel="stylesheet" type="text/css" media="all">
+    <script src="http://code.jquery.com/jquery-latest.js" type="text/javascript"></script>
+    <script src="{{ ASSET_PATH }}/vallenato/vallenato.js" type="text/javascript"></script>
+    <link rel="stylesheet" href="{{ ASSET_PATH }}/css/vallenato.css" type="text/css" media="screen">
   </head>
 
   <body>
@@ -70,15 +73,18 @@
                   <a href="{{ site.kiji_url }}/getstarted/#Quick_Start_Guide">Quick Start Guide</a>
                 </li>
                 <li class="menu-item">
-                  <a href="{{ HOME_PATH}}tutorial/phonebook-tutorial">Phonebook Tutorial</a>
+                  <a href="{{ site.tutorial_url }}.html">Tutorials</a>
                 </li>
                 <li class="menu-item">
-                  <a href="{{ HOME_PATH}}userguide/schema/1.0.0-rc1/kiji-schema-overview">
-                    User Guide
+                  <a href="{{ site.userguide_url }}.html">
+                    User Guides
                   </a>
                 </li>
                 <li class="menu-item">
-                  <a href="{{ HOME_PATH }}apidocs">API Reference</a>
+                  <a href="{{  site.api_url  }}">API Reference</a>
+                </li>
+                <li class="menu-item">
+                  <a href="https://github.com/kijiproject/wiki/wiki">Wiki</a>
                 </li>
               </ul>
             </li>

_includes/themes/twitter/post.html

@@ -1,5 +1,5 @@
 <div class="row-fluid">
-  <div class="span8">
+  <div class="span9">
     <div class="page-header">
       <h1>{{ page.title }}</h1>
     </div>
@@ -8,25 +8,35 @@ <h1>{{ page.title }}</h1>
 
     <div class="pagination">
       <ul>
-      {% if page.tags contains 'schema-ug' %}
-        {% assign pages = site.tags.schema-ug %}
-      {% elsif page.tags contains 'article' %}
-        {% assign pages = site.tags.article %}
-      {% endif %}
+    {% if page.tags contains 'schema-ug' %}
+      {% assign title = 'KijiSchema User Guide' %}
+      {% assign pages = site.tags.schema-ug %}
+    {% elsif page.tags contains 'mapreduce-ug' %}
+      {% assign title = 'KijiMR User Guide' %}
+      {% assign pages = site.tags.mapreduce-ug %}
+    {% elsif page.tags contains 'phonebook' %}
+      {% assign title = 'Phonebook Tutorial'  %}
+      {% assign pages = site.tags.phonebook %}
+    {% elsif page.tags contains 'music' %}
+      {% assign title = 'Music Recommendation Tutorial'  %}
+      {% assign pages = site.tags.music %}
+    {% endif %}
       {% capture maxpages %}{{ pages | size }}{% endcapture %}
 
       {% if page.order == 1 %}
         <li class="prev disabled"><a>&larr; Previous</a></li>
       {% else %}
         {% capture prevOrder %}{{ page.order | minus:1 }}{% endcapture %}
         {% for subpage in pages %}
-          {% capture curOrder %}{{ subpage.order }}{% endcapture %}
-          {% if curOrder == prevOrder %}
-            <li class="prev">
-              <a href="{{ BASE_PATH }}{{ subpage.url }}" title="{{ subpage.title }}">
-              &larr; Previous
-              </a>
-            </li>
+          {% if subpage.categories == page.categories %}
+            {% capture curOrder %}{{ subpage.order }}{% endcapture %}
+            {% if curOrder == prevOrder %}
+              <li class="prev">
+                <a href="{{ BASE_PATH }}{{ subpage.url }}" title="{{ subpage.title }}">
+                &larr; Previous
+                </a>
+              </li>
+            {% endif %}
           {% endif %}
         {% endfor %}
       {% endif %}
@@ -37,27 +47,35 @@ <h1>{{ page.title }}</h1>
       {% else %}
         {% capture nextOrder %}{{ page.order | plus:1 }}{% endcapture %}
         {% for subpage in pages %}
-          {% capture curOrder %}{{ subpage.order }}{% endcapture %}
-          {% if curOrder == nextOrder %}
-            <li class="next">
-              <a href="{{ BASE_PATH }}{{ subpage.url }}" title="{{ subpage.title }}">
-              Next &rarr;
-              </a>
-            </li>
+          {% if subpage.categories == page.categories %}
+            {% capture curOrder %}{{ subpage.order }}{% endcapture %}
+            {% if curOrder == nextOrder %}
+              <li class="next">
+                <a href="{{ BASE_PATH }}{{ subpage.url }}" title="{{ subpage.title }}">
+                Next &rarr;
+                </a>
+              </li>
+            {% endif %}
           {% endif %}
         {% endfor %}
       {% endif %}
       </ul>
     </div>
   </div>
 
-  <div class="span4">
+  <div class="span3">
     {% if page.tags contains 'schema-ug' %}
-      {% assign title = 'User Guide' %}
+      {% assign title = 'KijiSchema User Guide' %}
       {% assign pages = site.tags.schema-ug %}
-    {% elsif page.tags contains 'article' %}
+    {% elsif page.tags contains 'mapreduce-ug' %}
+      {% assign title = 'KijiMR User Guide' %}
+      {% assign pages = site.tags.mapreduce-ug %}
+    {% elsif page.tags contains 'phonebook' %}
       {% assign title = 'Phonebook Tutorial'  %}
-      {% assign pages = site.tags.article %}
+      {% assign pages = site.tags.phonebook %}
+    {% elsif page.tags contains 'music' %}
+      {% assign title = 'Music Recommendation Tutorial'  %}
+      {% assign pages = site.tags.music %}
     {% endif %}
     {% include side-toc.html %}
   </div>