You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@buildr.apache.org by Assaf Arkin <ar...@intalio.com> on 2009/03/16 23:57:30 UTC
Update to site and documentation
Last week I switched our documentation system to use Jekyll[1]. Before the
switch we used Docter to generate the Web site from Textile documents and
HAML templates. Jekyll replaces that with Textile documents and Liquid
templates.
The main reason for the switch: I have a strong preference to maintain as
little code as possible, and since I was the one maintaining Docter, I was
also always on the lookup to replace it with other people's code. Jekyll was
built for Github page[2], so it's bound to get more care and attention. It's
also, for those of you using Github pages, one less tool to learn.
The only change to the Textile files was the title/layout header that Jekyll
requires and using different tags to markup code snippets. Syntax
highlighting is now done by the more powerful Pygments, a Python app. PDF
generation still done by PrinceXML.
If you like the idea of using Textile to generate HTML and PDF, there are a
few more tips on my blog[3].
Another change, we're not using the Hanna template for the API documentation
(RDocs). If you look at the left-side navigation pane[4], you'll notice a
search bar that does as-you-type method search across all classes/modules.
While on the subject of documentation, the Web site (and PDF) have two
sections called Recipes and Troubleshooting. The Wiki has two sections
called "Buildr How Tos" and "Common Problems and Solutions". I'd like to
consolidate both.
The Wiki is much easier to edit than the Web site, so my preference right
now is to consolidate these duplicates and move them over to the Wiki, with
a link from the Web site navigation. Where it says Recipes right now it will
say HowTo and link to the Wiki instead of another page on the site.
The downside is that these two pages will no longer be part of the PDF.
Assaf
[1] http://github.com/mojombo/jekyll/
[2] http://pages.github.com/
[3]
http://blog.labnotes.org/2009/03/14/buildr-how-we-generate-the-documentation-web-site-and-pdf/
[4] http://buildr.apache.org/rdoc/
Re: Update to site and documentation
Posted by Alex Boisvert <bo...@intalio.com>.
I've uploaded a new version of the website + PDF which should fix this
now. It should get sync'ed to the main server and the mirrors within a
couple hours.
alex
On Mon, Apr 27, 2009 at 11:17 AM, Alex Boisvert <bo...@intalio.com>wrote:
> Yes, we are working on it. It works on one of my machine, but not on the
> machine where I did the release. Should be fixed today.
>
> alex
>
>
>
> On Mon, Apr 27, 2009 at 11:14 AM, Jeremy Huiskamp <
> jeremy.huiskamp@karoshealth.com> wrote:
>
>> I'm not sure if this is related, but I'm noticing that example code in the
>> documentation doesn't seem to be coming through, either on the website or in
>> the pdf version. I took a brief look at the source and it looks like
>> anything inside "<notextile>{% highlight foo %}" tags is missing.
>> Sorry if this has already been reported. A quick scan of jira and the
>> mailing lists doesn't turn up anything...
>>
>>
>> On 9/14/31 2:59 PM, Assaf Arkin wrote:
>>
>>> Last week I switched our documentation system to use Jekyll[1]. Before
>>> the
>>> switch we used Docter to generate the Web site from Textile documents and
>>> HAML templates. Jekyll replaces that with Textile documents and Liquid
>>> templates.
>>>
>>> The main reason for the switch: I have a strong preference to maintain as
>>> little code as possible, and since I was the one maintaining Docter, I
>>> was
>>> also always on the lookup to replace it with other people's code. Jekyll
>>> was
>>> built for Github page[2], so it's bound to get more care and attention.
>>> It's
>>> also, for those of you using Github pages, one less tool to learn.
>>>
>>> The only change to the Textile files was the title/layout header that
>>> Jekyll
>>> requires and using different tags to markup code snippets. Syntax
>>> highlighting is now done by the more powerful Pygments, a Python app. PDF
>>> generation still done by PrinceXML.
>>>
>>> If you like the idea of using Textile to generate HTML and PDF, there are
>>> a
>>> few more tips on my blog[3].
>>>
>>>
>>> Another change, we're not using the Hanna template for the API
>>> documentation
>>> (RDocs). If you look at the left-side navigation pane[4], you'll notice a
>>> search bar that does as-you-type method search across all
>>> classes/modules.
>>>
>>>
>>> While on the subject of documentation, the Web site (and PDF) have two
>>> sections called Recipes and Troubleshooting. The Wiki has two sections
>>> called "Buildr How Tos" and "Common Problems and Solutions". I'd like to
>>> consolidate both.
>>>
>>> The Wiki is much easier to edit than the Web site, so my preference right
>>> now is to consolidate these duplicates and move them over to the Wiki,
>>> with
>>> a link from the Web site navigation. Where it says Recipes right now it
>>> will
>>> say HowTo and link to the Wiki instead of another page on the site.
>>>
>>> The downside is that these two pages will no longer be part of the PDF.
>>>
>>> Assaf
>>>
>>>
>>> [1] http://github.com/mojombo/jekyll/
>>> [2] http://pages.github.com/
>>> [3]
>>>
>>> http://blog.labnotes.org/2009/03/14/buildr-how-we-generate-the-documentation-web-site-and-pdf/
>>> [4] http://buildr.apache.org/rdoc/
>>>
>>>
>>>
>>
>
Re: Update to site and documentation
Posted by Alex Boisvert <bo...@intalio.com>.
Yes, we are working on it. It works on one of my machine, but not on the
machine where I did the release. Should be fixed today.
alex
On Mon, Apr 27, 2009 at 11:14 AM, Jeremy Huiskamp <
jeremy.huiskamp@karoshealth.com> wrote:
> I'm not sure if this is related, but I'm noticing that example code in the
> documentation doesn't seem to be coming through, either on the website or in
> the pdf version. I took a brief look at the source and it looks like
> anything inside "<notextile>{% highlight foo %}" tags is missing.
> Sorry if this has already been reported. A quick scan of jira and the
> mailing lists doesn't turn up anything...
>
>
> On 9/14/31 2:59 PM, Assaf Arkin wrote:
>
>> Last week I switched our documentation system to use Jekyll[1]. Before the
>> switch we used Docter to generate the Web site from Textile documents and
>> HAML templates. Jekyll replaces that with Textile documents and Liquid
>> templates.
>>
>> The main reason for the switch: I have a strong preference to maintain as
>> little code as possible, and since I was the one maintaining Docter, I was
>> also always on the lookup to replace it with other people's code. Jekyll
>> was
>> built for Github page[2], so it's bound to get more care and attention.
>> It's
>> also, for those of you using Github pages, one less tool to learn.
>>
>> The only change to the Textile files was the title/layout header that
>> Jekyll
>> requires and using different tags to markup code snippets. Syntax
>> highlighting is now done by the more powerful Pygments, a Python app. PDF
>> generation still done by PrinceXML.
>>
>> If you like the idea of using Textile to generate HTML and PDF, there are
>> a
>> few more tips on my blog[3].
>>
>>
>> Another change, we're not using the Hanna template for the API
>> documentation
>> (RDocs). If you look at the left-side navigation pane[4], you'll notice a
>> search bar that does as-you-type method search across all classes/modules.
>>
>>
>> While on the subject of documentation, the Web site (and PDF) have two
>> sections called Recipes and Troubleshooting. The Wiki has two sections
>> called "Buildr How Tos" and "Common Problems and Solutions". I'd like to
>> consolidate both.
>>
>> The Wiki is much easier to edit than the Web site, so my preference right
>> now is to consolidate these duplicates and move them over to the Wiki,
>> with
>> a link from the Web site navigation. Where it says Recipes right now it
>> will
>> say HowTo and link to the Wiki instead of another page on the site.
>>
>> The downside is that these two pages will no longer be part of the PDF.
>>
>> Assaf
>>
>>
>> [1] http://github.com/mojombo/jekyll/
>> [2] http://pages.github.com/
>> [3]
>>
>> http://blog.labnotes.org/2009/03/14/buildr-how-we-generate-the-documentation-web-site-and-pdf/
>> [4] http://buildr.apache.org/rdoc/
>>
>>
>>
>
Re: Update to site and documentation
Posted by Jeremy Huiskamp <je...@karoshealth.com>.
I'm not sure if this is related, but I'm noticing that example code in
the documentation doesn't seem to be coming through, either on the
website or in the pdf version. I took a brief look at the source and it
looks like anything inside "<notextile>{% highlight foo %}" tags is
missing.
Sorry if this has already been reported. A quick scan of jira and the
mailing lists doesn't turn up anything...
On 9/14/31 2:59 PM, Assaf Arkin wrote:
> Last week I switched our documentation system to use Jekyll[1]. Before the
> switch we used Docter to generate the Web site from Textile documents and
> HAML templates. Jekyll replaces that with Textile documents and Liquid
> templates.
>
> The main reason for the switch: I have a strong preference to maintain as
> little code as possible, and since I was the one maintaining Docter, I was
> also always on the lookup to replace it with other people's code. Jekyll was
> built for Github page[2], so it's bound to get more care and attention. It's
> also, for those of you using Github pages, one less tool to learn.
>
> The only change to the Textile files was the title/layout header that Jekyll
> requires and using different tags to markup code snippets. Syntax
> highlighting is now done by the more powerful Pygments, a Python app. PDF
> generation still done by PrinceXML.
>
> If you like the idea of using Textile to generate HTML and PDF, there are a
> few more tips on my blog[3].
>
>
> Another change, we're not using the Hanna template for the API documentation
> (RDocs). If you look at the left-side navigation pane[4], you'll notice a
> search bar that does as-you-type method search across all classes/modules.
>
>
> While on the subject of documentation, the Web site (and PDF) have two
> sections called Recipes and Troubleshooting. The Wiki has two sections
> called "Buildr How Tos" and "Common Problems and Solutions". I'd like to
> consolidate both.
>
> The Wiki is much easier to edit than the Web site, so my preference right
> now is to consolidate these duplicates and move them over to the Wiki, with
> a link from the Web site navigation. Where it says Recipes right now it will
> say HowTo and link to the Wiki instead of another page on the site.
>
> The downside is that these two pages will no longer be part of the PDF.
>
> Assaf
>
>
> [1] http://github.com/mojombo/jekyll/
> [2] http://pages.github.com/
> [3]
> http://blog.labnotes.org/2009/03/14/buildr-how-we-generate-the-documentation-web-site-and-pdf/
> [4] http://buildr.apache.org/rdoc/
>
>
Re: Update to site and documentation
Posted by Alex Boisvert <bo...@intalio.com>.
On Wed, Mar 18, 2009 at 9:14 AM, Assaf Arkin <ar...@intalio.com> wrote:
> We have Recipes and Buildr How Tos. I'd like to consolidate these.
>
> We have Troubleshooting and Common Problems and Solutions. I'd like to
> consolidate these.
>
> That means out of the site/PDF and onto the Wiki.
Then I wholeheartedly agree.
alex
Re: Update to site and documentation
Posted by Assaf Arkin <ar...@intalio.com>.
On Wed, Mar 18, 2009 at 5:52 AM, Alex Boisvert <bo...@intalio.com> wrote:
> On Mon, Mar 16, 2009 at 3:57 PM, Assaf Arkin <ar...@intalio.com> wrote:
>
> > Last week I switched our documentation system to use Jekyll[1]. Before
> the
> > switch we used Docter to generate the Web site from Textile documents and
> > HAML templates. Jekyll replaces that with Textile documents and Liquid
> > templates.
>
>
> Nice work! I'm happy to use a documentation system that has more traction
> while retaining the character of Docter.
>
> While on the subject of documentation, the Web site (and PDF) have two
> > sections called Recipes and Troubleshooting. The Wiki has two sections
> > called "Buildr How Tos" and "Common Problems and Solutions". I'd like to
> > consolidate both.
>
>
> My preference would be to keep them separate (recipes vs troubleshooting)
> since I think they are used under different situations.
That question didn't come out right.
We have Recipes and Buildr How Tos. I'd like to consolidate these.
We have Troubleshooting and Common Problems and Solutions. I'd like to
consolidate these.
That means out of the site/PDF and onto the Wiki.
Assaf
>
>
> The Wiki is much easier to edit than the Web site, so my preference right
> > now is to consolidate these duplicates and move them over to the Wiki,
> with
> > a link from the Web site navigation. Where it says Recipes right now it
> > will
> > say HowTo and link to the Wiki instead of another page on the site.
>
>
> Agreed.
>
> alex
>
Re: Update to site and documentation
Posted by Alex Boisvert <bo...@intalio.com>.
On Mon, Mar 16, 2009 at 3:57 PM, Assaf Arkin <ar...@intalio.com> wrote:
> Last week I switched our documentation system to use Jekyll[1]. Before the
> switch we used Docter to generate the Web site from Textile documents and
> HAML templates. Jekyll replaces that with Textile documents and Liquid
> templates.
Nice work! I'm happy to use a documentation system that has more traction
while retaining the character of Docter.
While on the subject of documentation, the Web site (and PDF) have two
> sections called Recipes and Troubleshooting. The Wiki has two sections
> called "Buildr How Tos" and "Common Problems and Solutions". I'd like to
> consolidate both.
My preference would be to keep them separate (recipes vs troubleshooting)
since I think they are used under different situations.
The Wiki is much easier to edit than the Web site, so my preference right
> now is to consolidate these duplicates and move them over to the Wiki, with
> a link from the Web site navigation. Where it says Recipes right now it
> will
> say HowTo and link to the Wiki instead of another page on the site.
Agreed.
alex