Reorganization and redesign

[mnapoli]

Fixes #35, #40, #41, #42

Relates to #22, #44

TODO:

• Write introduction guides for categories and subcategories
• Maybe reorganize some guides in "Develop" to make the left menu clearer

Things to watch out:

• I have renamed some guides, splitted some into smaller ones… I have set up redirects but for links that link to a specific section of the guide (e.g. tests#travis-ci) they might be redirected with loosing the #travis-ci… We have to decide if that's acceptable.

I've reorganized the sections/menu as discussed in #35:

• Home
• Integrate
• Develop (now contains guides for plugins + how piwik works/contributing)
• API reference
• Changelog
• Support

I've hidden "Design" for now (which contains guides for theming) per @mattab's request: the documentation is not good enough.

I've simplified the UI/templates/codebase, we now have:

• the home page
• guides

There is no "category home page" anymore. The idea is to do something like Wordpress' developer documentation: the category home page is actually a guide that introduces the category. The left menu should do the rest (see just below).

Navigation through the category is now done with the left menu which is always visible and which is focused mainly on listing all guides of the category (previously it listed by default the sections of the current guide: that is now below).

Navigating through a long guide is less practical with this design, but this is OK: we want to write smaller guides (like on Wordpress). Smaller guides are easier to read, easier to write and maintain. And by listing smaller guides hierarchically (like Wordpress again) makes the whole thing much easier for visitors.

I've splitted the MVC guide for example into (see the screenshot):

• MVC guide introduction
• How Piwik handles HTTP requests
• Models (APIs)
• Views
• Controllers

This is much easier to navigate and read for visitors (at least we think so), so we should try to do the same with other guides.

I've also improved (hopefully) the website design. Screenshots:

[mnapoli]

I think this is ready to be merged, maybe checkout the branch locally and give it a spin?

Also:

Things to watch out:

• I have renamed some guides, splitted some into smaller ones… I have set up redirects but for links that link to a specific section of the guide (e.g. tests#travis-ci) they might be redirected with loosing the #travis-ci… We have to decide if that's acceptable.

FYI I have rewritten links in the developer documentation.

[mattab]

I'm merging and we'll see what happens live! Good to see such progress

[mnapoli]

I forgot one thing: now to make things simpler (hopefully) guides declare in which category they are. To do this, I've used Front YAML, which is what is used in blog engines/static websites based on Markdown (exactly like here so it makes sense).

Front YAML is YAML at the top of the document, placed in ---:

---
category: Develop
---
# The Core Team Workflow

blah blah…

We can also define previous/next guides like this, and also sub-guides:

---
category: Develop
subGuides:
  - http-request-handling
  - mvc-models
  - mvc-views
  - mvc-controllers
---
# MVC (Model-View-Controller)

## About this guide

**Read this guide if**

[mattab]

@mnapoli This front yaml sounds good (never heard of it before)! could you maybe add a note in the doc https://github.com/piwik/developer-documentation/#adding-a-new-guide ?

[mnapoli]

@mattab will do