Code Style Guidelines

This is the Holy Grail of contributing your documentation. It is a collection of guidelines (and in some cases strict rules) to keep things tidy and consistent.

Table of Contents

Page Titles

To show proper page titles for the documentation pages define the parent and title properties at the frontmatter section.

Titles are generated based on keys defined at the localization files.

Guidelines
parent property
The parent value should be the data/docs.yml documentation root key where the page belongs to. It is not required and it is used to generate proper page <title/>.
For index pages just use the title property.
title property
The title should match the data/docs.yml documentation pages entry title value.
Short Description
The short_description translation is required for the Documentation page.
Keep locales clean
Use alphabetical order for localization keys.
Remove any localizations you added but you are not actually being used.
Example

For the Analytics project, we update the locales/en.yml locale with the analytics parent title translation under the titles section and the proper translations for each of the documentation pages under thedocs section:

titles:
  analytics: 'Analytics'
...
docs:
  analytics:
    short_description: 'Analytics is a platform that...'
    overview: 'Overview'
    settings: 'Settings'

Then, at the frontmatter of settings.html.md.erb page we define:

---
parent: analytics
title: settings
---
Result
Settings | Analytics

Table Of Contents

The "Table of Contents" is auto-generated and contains the 2nd and 3rd level page sections (<h2>, <h3> headings).

Guidelines
Place of ToC
The "Table of Contents" should be printed right after the main page title <h1> and the introductory page description.
Example

Print the "Table of Contents" of a documentation page:

# Page Title

Short introduction should be here.

<%= partial 'partials/toc' %>

Edit On GitHub

Here at Skroutz we OSS and we show it. We encourage everyone to contribute to our documentation by including a link for editing the current page on GitHub at the <h1/> heading of each page.

Example

Include an "Edit on GitHub" link for the current documentation page:

# Page Title <%= edit_link %>

Code Examples

There are 2 ways to render a code example:

  1. use an inline code block
  2. use a resource file from resources/code_examples/ directory

If your example is a command or an instruction consider using the terminal command style.

Inline code blocks

To render a code block use the three tildes (~~~ ) as starting and ending lines.

Guidelines
Use fenced code blocks
Although you can specify a code block with indented lines (4 spaces or 1 tab), it is better to use the fenced code blocks as proposed.
Use Syntax Highlight
Start the code block with ~~~ language to enable sexy syntax highlight for the code block examples. The list of supported lexers can be found here.
Avoid large inline code examples
If you need to include a relatively large code example (e.g. 20+ lines) you should avoid placing it inline the page. You should extract it and put it inside resources/code_examples/<mydoc>/ directory.
See how to display code examples from resource files.

Code examples from resource file

For large code examples (e.g. 20+ code lines) you should consider extracting it to a code example file and then embed it into the page. It will be a lot easier to maintain it.

Example

We need to include an 10-line code snippet for Analytics that has to be flavored. Inside resources/code_examples/ we create the analytics directory and then a directory for each flavor:

resources/
+-- code_examples/
    +-- analytics/
        +-- alve/
            +-- js_snippet.yml
        +-- scrooge/
            +-- js_snippet.yml
        +-- skroutz/
            +-- js_snippet.yml

The js_snippet.yml file has the following syntax:

:language: html
:code: |
  <!-- Add the Tracking Script and Connect to your Account -->
  <script>
    (function(a,b,c,d,e,f,g){a['<%=flavor.capitalize%>AnalyticsObject']=e;a[e]= a[e] || function(){
      (a[e].q = a[e].q || []).push(arguments);};f=b.createElement(c);f.async=true;
      f.src=d;g=b.getElementsByTagName(c)[0];g.parentNode.insertBefore(f,g);
    })(window,document,'script','https://<%=settings.analytics_domain%>/skroutza.min.js','<%=flavor%>_analytics');

    <%=flavor%>_analytics('session', 'connect', 'SA-XXXX-YYYY');  // Connect your Account.
  </script>

Embed the flavored js_snippet.yml of the Analytics project:

<%= render_code_from_file 'analytics/js_snippet' %>
Result
<!-- Add the Tracking Script and Connect to your Account -->
<script>
  (function(a,b,c,d,e,f,g){a['SkroutzAnalyticsObject']=e;a[e]= a[e] || function(){
    (a[e].q = a[e].q || []).push(arguments);};f=b.createElement(c);f.async=true;
    f.src=d;g=b.getElementsByTagName(c)[0];g.parentNode.insertBefore(f,g);
  })(window,document,'script','https://skroutza.skroutz.gr/skroutza.min.js','skroutz_analytics');

  skroutz_analytics('session', 'connect', 'SA-XXXX-YYYY');  // Connect your Account.
</script>

Terminal commands

For terminal commands and other instructions do not use fenced code blocks. Instead wrap the block in <pre class="terminal"></pre>.

Example
<pre class="terminal">
$ curl https://www.skroutz.gr/oauth2/address?oauth_token=124fFAGRNJru1FTasz70...
</pre>
Result
$ curl https://www.skroutz.gr/oauth2/address?oauth_token=124fFAGRNJru1FTasz70...

Notes and Alerts

To add a Note use the MarkDown blockquote notation (>). If you like to render an info or danger types of alert you have to use HTML. Checkout the available Bootstrap Alerts.

Example
> ##### Note
> This is a very sexy **note**.
Result
Note

This is a very sexy note.

Definition Lists

Example
Term 1
: The description goes here

Term 2
: The description goes here
Result
Term 1
The description goes here
Term 2
The description goes here

Tables

Example
Name     | Type   | Value                                                      | Required | Description
-------- | ------ | ---------------------------------------------------------- | -------- | ---------------------
`attr1`  | String | `val1` <small class="mark">default</small>, `val2`, `val3` | Yes      | Attribute description
`attr2`  | Number | `10`, `20` <small class="mark">default</small>             | Yes      | Attribute description
`attr3`  | Array  | `[10, 20]`                                                 | No       | Attribute description
Result
Name Type Value Required Description
attr1 String val1 default, val2, val3 Yes Attribute description
attr2 Number 10, 20 default Yes Attribute description
attr3 Array [10, 20] No Attribute description

Flavored Data

Use <%= settings.<key> %> to access data fromdata/{flavor}.yml file based on the current flavor.

Example
# with FLAVOR=alve
<% settings.api_domain %>
#=> api.alve.com

# with FLAVOR=scrooge
<% settings.site_name.capitalize %>
#=> Scrooge

# with FLAVOR=skroutz
<% settings.full_company_name %>
#=> Skroutz S.A.