Permalink
Fetching contributors…
Cannot retrieve contributors at this time
282 lines (209 sloc) 7.9 KB
---
parent: contribute
title: add documentation
---
# Add Documentation <%= edit_link %>
Follow this guide to add a new documentation.
<%= partial 'partials/toc' %>
## Introduction
We'll use the *Analytics* project as an example to guide you how to add a new
documentation section.
## Documentation Directory
The first step you have to do is create the directory that the documentation will
live in and be served from.
The documentation directory name should be comprehensive, representative and
future proof. Keep in mind that it will be part of the URL path to access the
documentation.
##### Guidelines
{:.collapsible .collapsed data-toggle="collapse" data-target="#documentation-directory-guidelines" /}
<div id="documentation-directory-guidelines" class="collapse" markdown="1">
Avoid flavored names
: Do not use flavored names (i.e. *alve*, *scrooge*, *skroutz*, etc.) for the
documentation directory, even if your project is only available for a single
flavor. It will make things a lot easier to maintain if something changes in
the future.
Group when appropriate
: If your project consists of sub-projects with separate documentations then you
should try to group them under a common directory.
Some bad documentation directory names are:
~~~ ruby
- cost-per-action # Consider `cpa` or `cost_per_action`.
- skroutzeasy # Avoid flavored names. Consider `easy`.
- api_v3 # Consider grouping, `api/v3`.
- elasticsearch-skroutz-greekstemmer # Too long and flavored. Consider `elasticsearch/stemmer`.
~~~
</div>
##### Example
For the *Analytics* project, a sane choice for the directory name would be
`analytics`. The documentation will live in:
~~~ css
source/
+-- localizable/
+-- analytics/
~~~
and it will be accessible at:
~~~ css
https://<%= settings.developer_domain %>/analytics/
~~~
## Index page
Each documentation directory **should** serve an index page.
##### Example
For the *Analytics* project we create the `index.html.md.erb` inside `analytics/`
directory.
~~~ css
source/
+-- localizable/
+-- analytics/
+-- index.html.md.erb
~~~
## Other pages
To add a documentation page just create a new file `<name>.html.md.erb` inside
your documentation directory.
##### Example
For example, we need the documentation of the *Analytics Settings API* to be a
single page within the *Analytics* documentation. To achieve this, we create the
`settings.html.md.erb` inside the `analytics/` documentation directory:
~~~ css
source/
+-- localizable/
+-- analytics/
+-- index.html.md.erb
+-- settings.html.md.erb
~~~
that will be accessible at:
~~~ css
https://<%= settings.developer_domain %>/analytics/settings/
~~~
## Sidebar Entry
The `sidebar` is auto-generated based on syntax and naming conventions. To have
the documentation appear in the sidebar:
1. Update `data/docs.yml` with a new entry of your documentation pages
2. Update `locales/` with the missing translations for all flavors
### Update `data/docs.yml`
Add a new entry for your documentation and define which pages should be visible
at the sidebar.
The `data/docs.yml` file holds the documentation structure. Each root element
defines a different documentation.
##### Schema
{:.collapsible .collapsed data-toggle="collapse" data-target="#data-docs-schema" /}
<div id="data-docs-schema" class="collapse" markdown="1">
The schema of a `data/docs.yml` root element is the following:
~~~ yaml
mydoc:
base: '/mydoc/'
featured: true
icon: 'fa-bug'
pages:
- { title: 'overview', url: '/mydoc/' }
- { title: 'doc_page_name' }
~~~
> ##### Note
> Make sure to update locale files with the missing translations.
##### Attributes
Name | Type | Required | Description
--------------| --------| ----------| ------------
`base` | String | Yes | The path to the documentation directory, e.g. `'analytics/'`.
`deprecated` | Boolean | No | Set to `true` to label a documentation as *deprecated*.
`featured` | Boolean | No | Set to `true` to make the documentation featured in the home page.
`flavors` | Array | No | Define which flavors the documentation will be available in.
`icon` | String | No | A [FontAwesome](http://fortawesome.github.io/Font-Awesome/icons/) icon to accompany the documentation. This is required in case of a featured documentation.
`pages` | Array | No | Define the pages to show in the documentation.
</div>
##### Guidelines
{:.collapsible .collapsed data-toggle="collapse" data-target="#data-docs-guidelines" /}
<div id="data-docs-guidelines" class="collapse" markdown="1">
Root keys are unique
: Obviously you should not use the same root key for different documents.
If the one you have selected is already taken, stop whining and pick another
one. Perhaps it's time to consider why that key was taken, find the team
responsible by running`git blame` on `data/docs.yml` and discuss the issue
with them.
Order matters
: The order of root keys is also the order that documents will appear in the
sidebar (and other places too, e.g. featured documentations, documentation
page, etc).
Pages
: Each `pages` entry is an inline collection with a required key `title`. The
`title` value **should match** the page filename. For example, for the
`analytics/settings.html.md.erb` page, the `pages` entry should be:
<br/>
`- { title: 'settings' }`
<br/>
The `title` value is also the key to the localization of the page title.
: As a convention, the first `pages` entry should be the *index* page. It must
set the `url` key to the base of the documentation. For example:
<br/>
`- { title: 'overview', url: '/analytics/' }`
<br/>
For consistency, the index page should have the title `overview`.
: If you need to link to an external page resource, set it with the `url` key:
<br/>
`- { title: 'settings', url: 'http://www.example.com/' }`
</div>
##### Example
The entry for the *Analytics* documentation is:
~~~ yaml
analytics:
base: '/analytics/'
featured: true
icon: 'fa-bar-chart-o'
pages:
- { title: 'overview', url: '/analytics/' }
- { title: 'settings' }
- { title: 'ecommerce' }
~~~
### Update `locales/`
After updating the `data/docs.yml` with the documentation pages, it is required
to update the locale files with the missing translations.
##### Example
For the *Analytics* project, we update the `locales/en.yml` locale with the
`analytics` parent title translation under the `titles` section:
~~~ yaml
titles:
analytics: 'Analytics'
~~~
and the proper translations for each of the documentation pages under the
`docs/analytics` section:
~~~ yaml
docs:
analytics:
short_description: 'Analytics is a platform that...'
overview: 'Overview'
settings: 'Settings'
~~~
## Localization
By default documentation is served in the English language for each flavor. Define
the `locale` property at the page [frontmatter](http://middlemanapp.com/basics/frontmatter/)
section to make it available in multiple languages for a given flavor.
##### Guidelines
{:.collapsible .collapsed data-toggle="collapse" data-target="#localization-guidelines" /}
<div id="localization-guidelines" class="collapse" markdown="1">
Locale
: You should define the proper `locale` rules for each of the translated pages,
otherwise you may end up with inconsistent page links.
</div>
##### Example
Define available locales at the [frontmatter](http://middlemanapp.com/basics/frontmatter/)
section.
~~~ yaml
---
locale:
alve:
- 'en'
- 'tr'
scrooge:
- 'en'
skroutz:
- 'en'
- 'el'
---
~~~
and render the available `page_locales` partial to notify the users that the
page is available in multiple locales.
~~~ erb
<%%= partial 'partials/page_locales' %>
~~~
## Starting Template
Use the following as a starting template for your documentation. You can [view
how the example looks](/contribution/example/) along with the available styling options.
<%= render_code_from_file "contribution/doc_page_tpl" %>