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 doc...@. 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:3...@. 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 p...@.
+<notextile><pre>
+{% highlight ruby %}
+define 'project' do
+ # Just a sample
+end
+{% endhighlight %}
+</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 <br> 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 @_s...@. 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'
