You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wicket.apache.org by da...@apache.org on 2010/08/13 00:36:34 UTC
svn commit: r985021 - in /wicket/common/site/trunk:
_site/contribute/write.html contribute/write.md
Author: dashorst
Date: Thu Aug 12 22:36:34 2010
New Revision: 985021
URL: http://svn.apache.org/viewvc?rev=985021&view=rev
Log:
Added writing documentation doc to site
Modified:
wicket/common/site/trunk/_site/contribute/write.html
wicket/common/site/trunk/contribute/write.md
Modified: wicket/common/site/trunk/_site/contribute/write.html
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/contribute/write.html?rev=985021&r1=985020&r2=985021&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/contribute/write.html (original)
+++ wicket/common/site/trunk/_site/contribute/write.html Thu Aug 12 22:36:34 2010
@@ -87,7 +87,7 @@
<ul>
<li>
<a href="http://www.apache.org/dyn/closer.cgi/wicket/1.4.10">Wicket 1.4</a>
- (<a href="http://wicket.apache.org/apidocs/1.4" title="JavaDocs of the latest stable release - 1.4.10">docs</a>)
+ (<a href="http://wicket.apache.org/apidocs/1.4" title="JavaDocs of the latest stable release - 1.4.x">docs</a>)
</li>
<li>
<a href="http://www.apache.org/dyn/closer.cgi/wicket/1.3.7">Wicket 1.3</a>
@@ -144,7 +144,95 @@
<div id="contentbody">
<h1>Write documentation</h1>
- <p>TODO</p>
+ <p>We use <a href='http://github.com/mojombo/jekyll'>jekyll</a> for writing our documentation on our main website. Publishing new content is as simple as regenerating the site and committing the changed files.</p>
+
+<h2 id='contents'>Contents</h2>
+
+<ul>
+<li><a href='#introduction'>Introduction</a></li>
+
+<li><a href='#install'>Install Jekyll</a></li>
+
+<li><a href='#checkout'>Check out from SVN</a></li>
+
+<li><a href='#run'>Run the site</a></li>
+
+<li><a href='#write'>Write some documentation</a></li>
+
+<li><a href='#update'>Update the site</a></li>
+</ul>
+
+<h2 id='introduction'>Introduction</h2>
+
+<p>The site is split into two parts: static content and the official Apache Wicket blog. The static content contains all the documentation that is more static (such as mailing lists, downloads, examples). The blog includes release announcements, adding new committers and other important Wicket related news.</p>
+
+<h2 id='install'>Install Jekyll</h2>
+
+<p>Follow the instructions available on the <a href='http://github.com/mojombo/jekyll'>Jekyll website</a>. Basically it boils down to:</p>
+<div class='highlight'><pre><code class='console'><span class='go'>gem install jekyll</span>
+</code></pre>
+</div>
+<h2 id='checkout'>Check out from SVN</h2>
+
+<p>Before you can edit the site, you need to check it out from SVN:</p>
+<div class='highlight'><pre><code class='console'><span class='go'>svn co https://svn.apache.org/repos/asf/wicket/common/site/trunk wicket-site</span>
+</code></pre>
+</div>
+<h2 id='run'>Run the site</h2>
+
+<p>You can run the website by starting jekyll in the checked out directory:</p>
+<div class='highlight'><pre><code class='console'><span class='go'>jekyll --server --auto</span>
+</code></pre>
+</div>
+<p>This not only runs the server, but watches for modifications and regenerates any modified files.</p>
+
+<p>You can check out the website running at <a href='http://localhost:4000'>localhost, port 4000</a>.</p>
+
+<h2 id='write'>Write some documentation</h2>
+
+<p>Jekyll can render HTML from markdown syntax and textile syntax. <strong>For our site we use markdown</strong>.</p>
+
+<h3 id='page_template'>Page template</h3>
+
+<p>Each page needs to have a YAML preamble that specifies the rendered template and other variables. If it doesn’t include the YAML preamble, it won’t be rendered correctly.</p>
+
+<p>Example preamble (includes the <code>---</code>):</p>
+<div class='highlight'><pre><code class='yaml'><span class='nn'>---</span>
+<span class='l-Scalar-Plain'>layout</span><span class='p-Indicator'>:</span> <span class='l-Scalar-Plain'>default</span>
+<span class='l-Scalar-Plain'>title</span><span class='p-Indicator'>:</span> <span class='l-Scalar-Plain'>Write documentation</span>
+<span class='nn'>---</span>
+</code></pre>
+</div>
+<h3 id='syntax_highlighting'>Syntax highlighting</h3>
+
+<p>If you have a need to render code in your templates and have it syntax highlighted, surround the code with {\% highlight java \%} (substitute java with the language you want highlighted.)</p>
+
+<h3 id='menu'>Menu</h3>
+
+<p>If you want your page linked from every page, include the link in <code>\_includes/navigation.html</code>.</p>
+
+<h3 id='blog_posts'>Blog posts</h3>
+
+<p>For news items such as release announcements, new committers and other happenings, it is appriorate to create a blog post. The blog post is automatically added to the front page and the RSS feed.</p>
+
+<p>The blog items are written using the normal Jekyll syntax. The filename needs to be formatted as <code>yyyy-mm-dd-title.md</code> and the blog item should start with a YAML preamble, similar to normal pages:</p>
+<div class='highlight'><pre><code class='yaml'><span class='nn'>---</span>
+<span class='l-Scalar-Plain'>layout</span><span class='p-Indicator'>:</span> <span class='l-Scalar-Plain'>post</span>
+<span class='l-Scalar-Plain'>title</span><span class='p-Indicator'>:</span> <span class='l-Scalar-Plain'>Wicket 1.4.7 released</span>
+<span class='nn'>---</span>
+</code></pre>
+</div>
+<h2 id='update'>Update the site</h2>
+
+<p>When you’re done with making your changes, please check the following:</p>
+
+<ul>
+<li>Do the modified files contain only those changes that you actually want to publish? (Use svn diff to check)</li>
+
+<li>Did you restart jekyll to generate the site if you modified a global file (e.g. _config.yml)?</li>
+</ul>
+
+<p>If these things are OK, you can either <a href='patch.html'>generate a patch</a> when you’re not a committer, or just commit the changes. In the latter case, the modifications are pushed immediately to the site and are live within a minute.</p>
</div>
<div id="clearer"></div>
<div id="footer"><span>
Modified: wicket/common/site/trunk/contribute/write.md
URL: http://svn.apache.org/viewvc/wicket/common/site/trunk/contribute/write.md?rev=985021&r1=985020&r2=985021&view=diff
==============================================================================
--- wicket/common/site/trunk/contribute/write.md (original)
+++ wicket/common/site/trunk/contribute/write.md Thu Aug 12 22:36:34 2010
@@ -3,4 +3,113 @@ layout: default
title: Write documentation
---
-TODO
\ No newline at end of file
+We use [jekyll](http://github.com/mojombo/jekyll) for writing our
+documentation on our main website. Publishing new content is as simple as
+regenerating the site and committing the changed files.
+
+## Contents ##
+
+* [Introduction](#introduction)
+* [Install Jekyll](#install)
+* [Check out from SVN](#checkout)
+* [Run the site](#run)
+* [Write some documentation](#write)
+* [Update the site](#update)
+
+## Introduction ## {#introduction}
+
+The site is split into two parts: static content and the official Apache
+Wicket blog. The static content contains all the documentation that is more
+static (such as mailing lists, downloads, examples). The blog includes release
+announcements, adding new committers and other important Wicket related news.
+
+## Install Jekyll ## {#install}
+
+Follow the instructions available on the [Jekyll
+website](http://github.com/mojombo/jekyll). Basically it boils down to:
+
+{% highlight console %}
+gem install jekyll
+{% endhighlight %}
+
+## Check out from SVN ## {#checkout}
+
+Before you can edit the site, you need to check it out from SVN:
+
+{% highlight console %}
+svn co https://svn.apache.org/repos/asf/wicket/common/site/trunk wicket-site
+{% endhighlight %}
+
+## Run the site ## {#run}
+
+You can run the website by starting jekyll in the checked out directory:
+
+{% highlight console %}
+jekyll --server --auto
+{% endhighlight %}
+
+This not only runs the server, but watches for modifications and regenerates
+any modified files.
+
+You can check out the website running at [localhost, port 4000](http://localhost:4000).
+
+## Write some documentation ## {#write}
+
+Jekyll can render HTML from markdown syntax and textile syntax. **For our site
+we use markdown**.
+
+### Page template ###
+
+Each page needs to have a YAML preamble that specifies the rendered template
+and other variables. If it doesn't include the YAML preamble, it won't be
+rendered correctly.
+
+Example preamble (includes the `---`):
+
+{% highlight yaml %}
+---
+layout: default
+title: Write documentation
+---
+{% endhighlight %}
+
+### Syntax highlighting ###
+
+If you have a need to render code in your templates and have it syntax
+highlighted, surround the code with \{\% highlight java \%\} (substitute java
+with the language you want highlighted.)
+
+### Menu ###
+
+If you want your page linked from every page, include the link in
+`\_includes/navigation.html`.
+
+### Blog posts ###
+
+For news items such as release announcements, new committers and other
+happenings, it is appriorate to create a blog post. The blog post is
+automatically added to the front page and the RSS feed.
+
+The blog items are written using the normal Jekyll syntax. The filename needs
+to be formatted as `yyyy-mm-dd-title.md` and the blog item should start with a
+YAML preamble, similar to normal pages:
+
+{% highlight yaml %}
+---
+layout: post
+title: Wicket 1.4.7 released
+---
+{% endhighlight %}
+
+## Update the site ## {#update}
+
+When you're done with making your changes, please check the following:
+
+* Do the modified files contain only those changes that you actually want to
+ publish? (Use svn diff to check)
+* Did you restart jekyll to generate the site if you modified a global file
+ (e.g. \_config.yml)?
+
+If these things are OK, you can either [generate a patch](patch.html) when
+you're not a committer, or just commit the changes. In the latter case, the
+modifications are pushed immediately to the site and are live within a minute.