You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by al...@apache.org on 2016/03/10 11:32:27 UTC
[02/10] brooklyn-docs git commit: Docs for the docs

Docs for the docs


Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/b5b21614
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/b5b21614
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/b5b21614

Branch: refs/heads/master
Commit: b5b21614cc03280860ff80883e7f22e939662e54
Parents: 5d6d845
Author: Duncan Godwin <du...@cloudsoftcorp.com>
Authored: Mon Mar 7 14:59:48 2016 +0000
Committer: Duncan Godwin <du...@cloudsoftcorp.com>
Committed: Mon Mar 7 16:54:43 2016 +0000

----------------------------------------------------------------------
 README.md                       |  8 +++--
 _plugins/page_structure.rb      |  6 ----
 contributing/index.md           | 15 ++++++++++
 contributing/inline-children.md | 54 +++++++++++++++++++++++++++++++++
 contributing/ordering.md        | 46 ++++++++++++++++++++++++++++
 contributing/pdf-manual.md      | 58 ++++++++++++++++++++++++++++++++++++
 contributing/site-structure.md  | 29 ++++++++++++++++++
 7 files changed, 208 insertions(+), 8 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b5b21614/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 5b6cf54..7d7d1e3 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,10 @@ familiarise yourself with the standard workflow for Apache Brooklyn:
 [CONTRIB]: https://brooklyn.apache.org/community/how-to-contribute-docs.html
 [COMMIT]: https://brooklyn.apache.org/developers/committers/index.html
 
+The documents are written in [kramdown](http://kramdown.gettalong.org/syntax.html) a superset of Markdown 
+which is processed into HTML using [Jekyll](https://jekyllrb.com/). In addition to the standard set of options
+and notation available with these platforms, a number of custom plug-ins have been implemented specifically
+for the Brooklyn docs. These are detailed in the [contributing to docs](https://brooklyn.apache.org/contributing) doc.  
 
 Workstation Setup
 -----------------
@@ -21,8 +25,8 @@ Workstation Setup
 First, if you have not already done so, clone the `brooklyn` repository and subprojects
 and set up the remotes as described in [Guide for committers][COMMIT].
 
-The Brooklyn documentation uses Markdown notation (what this file is written in)
-and the Jekyll process. This in turn requires Ruby and gems as described in the `Gemfile`:
+The Brooklyn documentation uses [Jekyll](https://jekyllrb.com/) to process the site content into HTML. 
+This in turn requires Ruby and gems as described in the `Gemfile`:
 install [RVM](http://rvm.io/) to manage Ruby installations and sets of Ruby gems.
 
     \curl -sSL https://get.rvm.io | bash -s stable

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b5b21614/_plugins/page_structure.rb
----------------------------------------------------------------------
diff --git a/_plugins/page_structure.rb b/_plugins/page_structure.rb
index fbfd5a2..07caf17 100644
--- a/_plugins/page_structure.rb
+++ b/_plugins/page_structure.rb
@@ -10,12 +10,6 @@ require "kramdown"
 
 module PageStructureUtils
   
-  class MyHash < Hash
-    def to_s
-      "cheese"
-    end
-  end
-  
   class ChildPage
     def initialize(yaml, content)
       @yaml=yaml

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b5b21614/contributing/index.md
----------------------------------------------------------------------
diff --git a/contributing/index.md b/contributing/index.md
new file mode 100644
index 0000000..21576dd
--- /dev/null
+++ b/contributing/index.md
@@ -0,0 +1,15 @@
+---
+layout: website-normal
+title: Contributing to the Docs
+check_directory_for_children: true
+---
+
+The Apache Brooklyn documentation is written in [kramdown](http://kramdown.gettalong.org/syntax.html){:target="_blank"} a superset of Markdown 
+which is processed into HTML using [Jekyll](https://jekyllrb.com/){:target="_blank"}. In addition to the standard set of options
+and notation available with these platforms, a number of custom plug-ins have been implemented specifically
+for the Apache Brooklyn docs. These are detailed below:
+
+Jekyll plug-ins are written in ruby and kept in the `_plugins` folder. Note that if you're using `jekyll serve` to
+display the site, changes to these plug-ins will not be reflected in the rendered site until jekyll is restarted. 
+
+{% child_content %}

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b5b21614/contributing/inline-children.md
----------------------------------------------------------------------
diff --git a/contributing/inline-children.md b/contributing/inline-children.md
new file mode 100644
index 0000000..d6270bb
--- /dev/null
+++ b/contributing/inline-children.md
@@ -0,0 +1,54 @@
+---
+section: Inline Children
+section_position: 2
+section_type: inline
+---
+
+### Inline Children
+
+In addition to the `children` property defining lower pages in the site structure, they can also be used to define
+inline sections within the current document. Inclusion in this way produces a menu link to an anchor in the current page.
+
+Below is an example from [/guide/ops/persistence/index.md](https://github.com/apache/brooklyn-docs/blob/master/guide/ops/persistence/index.md){:target="_blank"}:
+
+{% highlight yaml %}
+children:
+- { section: Command Line Options }
+- { section: File-based Persistence }
+- { section: Object Store Persistence }
+- { section: Rebinding to State }
+- { section: Writing Persistable Code }
+- { section: Persisted State Backup }
+{% endhighlight %}
+
+Inline sections can also be detected from separate, child `.md` files. Including the tag `check_directory_for_children: true`
+in the YAML front matter of a page causes the site structure plug-in to look through the current directory for any `.md` files
+containing `section_type: inline` in the YAML front matter.
+
+The content from these inline sections can then be included in the page content using the liquid tag `child_content`. This is shown below
+in an example from [/guide/ops/locations/index.md](https://github.com/apache/brooklyn-docs/blob/master/guide/ops/locations/index.md){:target="_blank"}:
+
+<pre>
+&#45;&#45;&#45;
+title: Locations
+layout: website-normal
+check_directory_for_children: true
+&#45;&#45;&#45;
+
+Locations are the environments to which Brooklyn deploys applications, including:
+
+Brooklyn supports a wide range of locations:
+
+* &lt;a href="#clouds"&gt;Clouds&lt;/a&gt;, where it will provision machines
+* &lt;a href="#localhost"&gt;Localhost&lt;/a&gt; (e.g. your laptop), 
+  where it will deploy via `ssh` to `localhost` for rapid testing
+* &lt;a href="#byon"&gt;BYON&lt;/a&gt;, where you "bring your own nodes",
+  specifying already-existing hosts to use
+* And many others, including object stores and online services
+
+Configuration can be set in `~/.brooklyn/brooklyn.properties`
+or directly in YAML when specifying a location.
+On some entities, config keys determining maching selection and provisioning behavior
+can also be set `in `provisioning.properties`.  
+
+{&#37; child_content &#37;}</pre>

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b5b21614/contributing/ordering.md
----------------------------------------------------------------------
diff --git a/contributing/ordering.md b/contributing/ordering.md
new file mode 100644
index 0000000..ff2a0f9
--- /dev/null
+++ b/contributing/ordering.md
@@ -0,0 +1,46 @@
+---
+section: Child Page Ordering
+section_position: 3
+section_type: inline
+---
+
+### Child Page Ordering
+
+Child pages are by default, ordered by their position in the `children` YAML front matter field. This can be changed using the property
+`section_position` in the child YAML. For children defined in the front matter this is put in the child object of the `children` array.
+
+For inline children, sourced using `check_directory_for_children: true`, this `section_position` property is put in the child file's YAML front matter.
+
+The format for `section_position` is that of software versioning, i.e `A.B... Z` where A, B etc are numbers of decreasing value. Position `1.1.0` would appear
+before version `1.0.4` for example. This allows an infinite number of sub pages between each `section_position`.
+
+Any un-versioned pages are automatically numbered to follow on from the last numbered page, or `1.1` if no pages are yet numbered. For
+example, if a numbered page, `1.4` is followed by a non-numbered page, the non-numbered page would be auto-numbered as `1.4.1`.
+
+For example, a set of children pages numbered like this:
+
+{% highlight yaml %}
+children:
+- { path: /guide/start/index.md, section_position: 3.1.2 }
+- { path: /guide/misc/download.md }
+- { path: /guide/concepts/index.md }
+- { path: /guide/yaml/index.md }
+- { path: /guide/java/index.md }
+- { path: /guide/ops/index.md, section_position: 2 }
+- { path: /guide/misc/index.md }
+{% endhighlight %}
+
+Would end up numbered like this:
+
+{% highlight yaml %}
+children:
+- { path: /guide/ops/index.md, section_position: 2 }
+- { path: /guide/misc/index.md, section_position: 2.1 }
+- { path: /guide/start/index.md, section_position: 3.1.2 }
+- { path: /guide/misc/download.md, section_position: 3.1.2.1 }
+- { path: /guide/concepts/index.md, section_position: 3.1.2.2 }
+- { path: /guide/yaml/index.md, section_position: 3.1.2.3 }
+- { path: /guide/java/index.md, section_position: 3.1.2.4 }
+{% endhighlight %}
+
+This ordering affects both the position of the child in the html menu and the order of content included with `child_content`.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b5b21614/contributing/pdf-manual.md
----------------------------------------------------------------------
diff --git a/contributing/pdf-manual.md b/contributing/pdf-manual.md
new file mode 100644
index 0000000..ef9e950
--- /dev/null
+++ b/contributing/pdf-manual.md
@@ -0,0 +1,58 @@
+---
+section: Single Page Manual & PDF
+section_position: 4
+section_type: inline
+---
+
+## Single Page Manual & PDF
+
+A single page overview of selections of the site are available in `zoneMergeManual` and `zoneMergeStarted`. These overviews are for the user manual
+and getting started guide respectively. The zone merge pages go through the [site structure](#site-structure), described above, and compile the files from this into a
+single HTML page.
+
+In order to do this, each page is iterated over in order and it's rendered content included in the page. The plug-in `regex_filter.rb` is used to re-write
+ &lt;a&gt; links from the structured site into a form which works on a single page. Links are re-written in the following manner:
+
+- If the link is from an external domain, leave it as an unaltered link
+- If the link is an anchor, convert to the anchor scheme used in the single page
+- If the link target is in the single page, change the link to point at the anchor in the single page
+- If the link is pointing at somewhere on the brooklyn site which is not included in this single page, point to the website with a specific version, so https://brooklyn.apache.org/v/0.9.0-SNAPSHOT/start/concept-quickstart.html for instance
+
+In addition, all images src's are re-written relative to the root directory.
+
+Pages can be masked from the compilation process by defining a `page_mask` in the YAML front matter of the zone merge file, then including this mask as `true` in the child page to exclude.
+These pages will then not be included in the compiled single page. Note that this will mask both the child page and any children of this masked page. 
+For example [zoneMergeStarted](https://github.com/apache/brooklyn-docs/blob/master/zoneMergeStarted.html){:target="_blank"} uses the mask `started-pdf-exclude`:
+ 
+{% highlight yaml %}
+title: Apache Brooklyn Manual
+layout: singlePage
+page_mask: started-pdf-exclude
+...
+{% endhighlight %}
+
+Then in latter pages, such as [/guide/ops/index.md](https://github.com/apache/brooklyn-docs/blob/master/guide/ops/index.md){:target="_blank"} include `started-pdf-exclude: true` to
+exclude this section from the getting started guide.
+
+{% highlight yaml %}
+title: Operations
+started-pdf-exclude: true
+...
+{% endhighlight %}
+
+This will exclude not only the operations page but all of the operations section.
+
+Specific content can be also be masked or unmasked at a page component level by specifying CSS show and hide classes:
+
+{% highlight yaml %}
+css_hide_class: usermanual-pdf-exclude
+css_show_class: usermanual-pdf-include
+{% endhighlight %}
+
+If the above YAML is included in the front matter of a zone merge file, the classes `usermanual-pdf-exclude` and `usermanual-pdf-include` will add or remove a
+`display: none` to a HTML object. In addition the single page theme files [singlePage.html](https://github.com/apache/brooklyn-docs/blob/master/_layouts/singlePage.html){:target="_blank"} and
+[singlePage.css](https://github.com/apache/brooklyn-docs/blob/master/style/css/singlePage.css) can be used to style only the single merged pages.
+
+### Conversion to PDF
+
+These single merged pages are then converted to PDF using wkhtmltopdf in the build scripts of this site.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/b5b21614/contributing/site-structure.md
----------------------------------------------------------------------
diff --git a/contributing/site-structure.md b/contributing/site-structure.md
new file mode 100644
index 0000000..c052e1c
--- /dev/null
+++ b/contributing/site-structure.md
@@ -0,0 +1,29 @@
+---
+section: Site Structure
+section_position: 1
+section_type: inline
+---
+
+## Site Structure
+
+The site structure and menus are built by a plug-in in `site_structure.rb`. This plug-in looks in the [YAML front matter](https://jekyllrb.com/docs/frontmatter/){:target="_blank"} 
+for child pages to build the structure, and breadcrumbs to determine the parent pages to display. 
+
+Child pages are a list of objects, stored in the field `children`. These are defined by string path to a file or a YAML 
+object with a `path` to another file, or a `link` to an external URL. In addition a `title` can be defined 
+for the text content of the HTML menu option. See the example below from 
+[/guide/index.md](https://github.com/apache/brooklyn-docs/blob/master/guide/index.md){:target="_blank"}
+
+{% highlight yaml %}
+breadcrumbs:
+- /website/documentation/index.md
+- index.md
+children:
+- { path: /guide/start/index.md }
+- { path: /guide/misc/download.md }
+- { path: /guide/concepts/index.md }
+- { path: /guide/yaml/index.md }
+- { path: /guide/java/index.md }
+- { path: /guide/ops/index.md }
+- { path: /guide/misc/index.md }
+{% endhighlight %}