[doc] Add "Writing Documentation"

docs/README.md

@@ -7,15 +7,16 @@ This site was built using the tomjohnson1492/documentation-theme-jekyll theme
 
 A Jekyll-based theme designed for documentation and help systems. See the link for detailed instructions on setting up and configuring everything. http://idratherbewriting.com/documentation-theme-jekyll/
 
+## Building using Bundler
 
-Build the site to see the instructions for using it. Or just go here: [http://idratherbewriting.com/documentation-theme-jekyll/](http://idratherbewriting.com/documentation-theme-jekyll/)
-
-Run `bundle exec jekyll serve --watch` to fire up Jekyll on local machine
-
-## Using Docker
-
-One time: `docker build --no-cache -t mydocs .`
-
-Now run the site with `docker run --rm=true -v "$PWD:/src" -p 4005:4005 mydocs serve -H 0.0.0.0`
+    bundle install # once
+    bundle exec jekyll serve
+
+Go to: http://localhost:4005/
+
+## Building using Docker
+
+    docker build --no-cache -t pmd-doc . # once
+    docker run --rm=true -v "$PWD:/src" -p 4005:4005 pmd-doc serve -H 0.0.0.0
 
 Go to: http://localhost:4005/

docs/_data/sidebars/pmd_sidebar.yml

@@ -123,6 +123,9 @@ entries:
     - title: Developer Resources
       url: /pmd_devdocs_development.html
       output: web, pdf
+    - title: Writing Documentation
+      url: /pmd_devdocs_writing_documentation.html
+      output: web, pdf
     - title: Code Style
       url: /pmd_devdocs_codestyle.html
       output: web, pdf

docs/pages/pmd/devdocs/writing_documentation.md

@@ -0,0 +1,140 @@
+---
+title: Writing Documentation
+last_update: August 2017
+permalink: pmd_devdocs_writing_documentation.html
+keywords: documentation, jekyll, markdown
+---
+
+PMD's documentation uses [Jekyll](https://jekyllrb.com/) with
+the [I'd rather be writing Jekyll Theme](http://idratherbewriting.com/documentation-theme-jekyll/index.html).
+
+Here are some quick tips.
+
+## Format
+
+The pages are in general in [Github Flavored Markdown](https://kramdown.gettalong.org/parser/gfm.html).
+
+## Structure
+
+All documentation is stored in the folder `docs/`. This is the folder, that github and the travis-ci scripts
+use to render the site.
+
+New pages are stored in the different subfolders under `pages`. The folder structure resembles the sidebar structure.
+Since all pages use a simple *permalink*, in the rendered html pages, all pages are flattened in one directory.
+This makes it easy to view the documentation also offline.
+
+## Building
+
+There are two ways, to execute jekyll:
+
+1.  Using [bundler](http://bundler.io/). This will install all the needed ruby packages locally and execute jekyll:
+
+        # this is required only once, to download and install the dependencies
+        bundle install
+        # this builds the documentation under _site
+        bundle exec jekyll build
+        # this runs a local webserver as http://localhost:4005
+        bundle exec jekyll serve
+
+2.  Using [docker](https://www.docker.com/). This will create a local docker image, into which all needed ruby
+    packages and jekyll is installed.
+
+        # this is required only once to create a local docker image named "pmd-doc"
+        docker build --no-cache -t pmd-doc .
+        # this builds the documentation under _site
+        docker run --rm=true -v "$PWD:/src" pmd-doc build -H 0.0.0.0
+        # this runs a local webserver as http://localhost:4005
+        docker run --rm=true -v "$PWD:/src" -p 4005:4005 pmd-doc serve -H 0.0.0.0
+
+The built site is stored locally in the (git ignored) directory `_site`. You can
+point your browser to `_site/index.html` to see the pmd documentation.
+
+Alternatively, you can start the local webserver, that will serve the documentation.
+Just go to http://localhost:4005.
+If a page is modified, the documentation will automatically be rendered again and
+all you need to do, is refreshing the page in your browser.
+
+
+## The sidebar
+
+The sidebar is stored as a YAML document under `_data/sidebars/pmd_sidebar.yml`.
+
+Make sure to add an entry there, whenever you create a new page.
+
+
+## The frontmatter
+
+Each page in jekyll begins with a YAML section at the beginning. This section
+is separated by 3 dashes (`---`). Example:
+
+    ---
+    title: Writing Documentation
+    last_update: August 2017
+    permalink: pmd_devdocs_writing_documentation.html
+    ---
+
+    Some Text
+
+    # Some header
+
+There are a couple of possible fields. Most important and always
+required are **title** and **permalink**.
+
+By default, a page **toc** (table of contents) is automatically generated.
+You can prevent this with "toc: false".
+
+You can add **keywords**, that will be used for the on-site search: "keywords: documentation, jekyll, markdown"
+
+It's useful to maintain a **last_update** field. This will be added at the bottom of the
+page.
+
+A **summary** can also be provided. It will be added in a box before the content.
+
+For a more exhaustive list, see [Pages - Frontmatter](http://idratherbewriting.com/documentation-theme-jekyll/mydoc_pages.html#frontmatter).
+
+
+## Alerts and Callouts
+
+See [Alerts](http://idratherbewriting.com/documentation-theme-jekyll/mydoc_alerts.html).
+
+For example, a info-box can be created like this:
+
+    {% include note.html content="This is a note." %}
+
+It renders as:
+
+{% include note.html content="This is a note." %}
+
+Other available types are:
+
+*   note.html
+*   tip.html
+*   warning.html
+*   important.html
+
+
+A callout is created like this:
+
+    {% include callout.html content="This is a callout of type default.<br/><br/>There are the following types available: danger, default, primary, success, info, and warning." type="default" %}
+
+It renders as:
+
+{% include callout.html content="This is a callout of type default.<br/><br/>There are the following types available: danger, default, primary, success, info, and warning." type="default" %}
+
+## Code samples with syntax highlighting
+
+This is as easy as:
+
+    ``` java
+    public class Foo {
+        public void bar() { System.out.println("x"); }
+    }
+    ```
+
+This looks as follows:
+
+``` java
+public class Foo {
+    public void bar() { System.out.println("x"); }
+}
+```