svn commit: r789453 - in /buildr/trunk: doc/contributing.textile doc/preface.textile rakelib/doc.rake rakelib/jekylltask.rb

[as...@apache.org]

Author: assaf
Date: Mon Jun 29 21:26:32 2009
New Revision: 789453

URL: http://svn.apache.org/viewvc?rev=789453&view=rev
Log:
Upgraded to Jekyll 0.5.2 with less known bugs

Preface ToC now uses HTML to apply class directly on ol (which somehow worked before w/Textile but no longer does)

Updated section about documentation (in contributing page) with information about Jekyll and how we use it.

Modified:
    buildr/trunk/doc/contributing.textile
    buildr/trunk/doc/preface.textile
    buildr/trunk/rakelib/doc.rake
    buildr/trunk/rakelib/jekylltask.rb

Modified: buildr/trunk/doc/contributing.textile
URL: http://svn.apache.org/viewvc/buildr/trunk/doc/contributing.textile?rev=789453&r1=789452&r2=789453&view=diff
==============================================================================
--- buildr/trunk/doc/contributing.textile (original)
+++ buildr/trunk/doc/contributing.textile Mon Jun 29 21:26:32 2009
@@ -176,17 +176,45 @@
 
 For simple typos and quick fixes, just send a message to the mailing list or log an issue in JIRA.
 
-If you end up rewriting a significant piece of text, or add new documentation (you rock!), send a patch.  Making documentation patches is fairly easy.  All the documentation is generated from text files in the @doc/pages@ directory, so all you need to do is check it out from SVN, edit, and @svn diff@ to create a patch.
+If you end up rewriting a significant piece of text, or add new documentation (you rock!), send a patch.  Making documentation patches is fairly easy.  All the documentation is generated from text files in the @doc/pages@ directory, so all you need to do is check it out from Git/SVN, edit, and @svn diff@ to create a patch.
 
 We use "Textile":http://www.textism.com/tools/textile/ as the markup language, it takes all of a few minutes to learn, it's intuitive to use, and produces clean HTML.  You can learn it all in a few minutes from the "Textile Reference Manual":http://redcloth.org/textile.  Also check out the "Textile Quick Reference":http://hobix.com/textile/quick.html.
 
-You can always check the documentation to see which conventions we use, and also a couple of extensions we have for styling source code (with syntax highlighting!) and handling footnotes.  The table of contents is auto-generated form H1/H2 headers.
+Syntax highlighting handled by "Pygments":http://pygments.org.  Use the special @highlight@ tag to separate code sample from the rest of the text and to tell Pygments which language to use.  For example:
 
-The tool we use for this is called Docter, which we developed specifically for Buildr, and use to create the Web site and printable PDF.  If you want to try it out you'll need to first @gem install docter@.  To generate a copy of the Web site, simple run @rake html@ .
-
-If you're thinking of editing the docs, and using @rake html@ to see what the HTML looks like, you may want to try something simpler.  Start by running the Docter Web server with @rake docter@ and then point your browser at @http://localhost:3000@.  To see your edits, simply refresh the page.
-
-Generating the PDF is a bit more tricky, we use the HTML in combination with print media CSS stylesheets and run them through the wonderful "PrinceXML":http://www.princexml.com/, so you'll need to install PrinceXML first before you can @rake pdf@.
+<notextile><pre>
+&#123;&#37; highlight ruby &#37;&#125;
+define 'project' do
+  # Just a sample
+end
+&#123;&#37; endhighlight &#37;&#125;
+</pre></notextile>
+
+Have a look at existing documentation to see writing conventions, specifically:
+
+* Separate paragraphs with two newlines.
+* Use one newline only if you need a &lt;br&gt; tag, otherwise, no newlines inside the paragraph.
+* When creating a new page, don't forget the YAML premable at the top (Jekyll needs the page title and layout).
+* The layout uses H1 to render the page title; only use H2 through H4 for the page content.
+* Use H2 headers for the major page sections.  Give each H2 header a unique ID so the table of contents can link to it.
+* Separating sentences with two spaces, just a convenience when editing in a text editor using monospaced fonts.
+* If in doubt, ask.
+
+To go from Textile to HTML we use "Jekyll":http://github.com/mojombo/jekyll.  You can use the @jekyll@ rake task to transform the files under @doc@ and create a copy of the Web site in the directory @_site@.  For example:
+
+{% highlight sh %}
+$ rake jekyll
+$ open _site/index.html
+{% endhighlight %}
+
+There is no live editing, but you can run @rake jekyll auto=true@, and when you update and save a Textile page it will regenerate the corresponding HTML page.
+
+To go from HTML to PDF we use "PrinceXML":http://www.princexml.com/.  The target file @buildr.pdf@ is generated by first running Jekyll and then merging the generated HTML pages into a single PDF document.  For example:
+
+{% highlight sh %}
+$ rake buildr.pdf
+$ open buildr.pdf
+{% endhighlight %}
 
 
 h2(#contributors).  Contributors

Modified: buildr/trunk/doc/preface.textile
URL: http://svn.apache.org/viewvc/buildr/trunk/doc/preface.textile?rev=789453&r1=789452&r2=789453&view=diff
==============================================================================
--- buildr/trunk/doc/preface.textile (original)
+++ buildr/trunk/doc/preface.textile Mon Jun 29 21:26:32 2009
@@ -4,17 +4,19 @@
 
 p(title). !images/zbuildr.png!
 
-#(toc) "Getting Started":getting_started.html
-# "Projects":projects.html
-# "Building":building.html
-# "Artifacts":artifacts.html
-# "Packaging":packaging.html
-# "Testing":testing.html
-# "Settings & Profiles":settings_profiles.html
-# "Languages":languages.html
-# "More Stuff":more_stuff.html
-# "Extending Buildr":extending.html
-# "Contributing":contributing.html
+<ol class='toc'>
+  <li>"Getting Started":getting_started.html</li>
+  <li>"Projects":projects.html</li>
+  <li>"Building":building.html</li>
+  <li>"Artifacts":artifacts.html</li>
+  <li>"Packaging":packaging.html</li>
+  <li>"Testing":testing.html</li>
+  <li>"Settings & Profiles":settings_profiles.html</li>
+  <li>"Languages":languages.html</li>
+  <li>"More Stuff":more_stuff.html</li>
+  <li>"Extending Buildr":extending.html</li>
+  <li>"Contributing":contributing.html</li>
+</ol>
 
 
 p(preface). Copyright 2007-2009 Apache Buildr

Modified: buildr/trunk/rakelib/doc.rake
URL: http://svn.apache.org/viewvc/buildr/trunk/rakelib/doc.rake?rev=789453&r1=789452&r2=789453&view=diff
==============================================================================
--- buildr/trunk/rakelib/doc.rake (original)
+++ buildr/trunk/rakelib/doc.rake Mon Jun 29 21:26:32 2009
@@ -59,7 +59,7 @@
 
 desc "Generate Buildr documentation as buildr.pdf"
 file 'buildr.pdf'=>'_site' do |task|
-  pages = File.read('doc/preface.textile').scan(/^#.*":(\S*)$/).flatten.map { |f| "_site/#{f}" }
+  pages = File.read('_site/preface.html').scan(/<li><a href=['"]([^'"]+)/).flatten.map { |f| "_site/#{f}" }
   sh 'prince', '--input=html', '--no-network', '--log=prince_errors.log', "--output=#{task.name}", '_site/preface.html', *pages
 end
 

Modified: buildr/trunk/rakelib/jekylltask.rb
URL: http://svn.apache.org/viewvc/buildr/trunk/rakelib/jekylltask.rb?rev=789453&r1=789452&r2=789453&view=diff
==============================================================================
--- buildr/trunk/rakelib/jekylltask.rb (original)
+++ buildr/trunk/rakelib/jekylltask.rb Mon Jun 29 21:26:32 2009
@@ -14,7 +14,7 @@
 # the License.
 
 
-#gem 'RedCloth', '4.2.0'
+gem 'mojombo-jekyll', '~> 0.5.2' # skip past some buggy versions
 require 'rake/tasklib'
 require 'jekyll'