GPLv3 or later
$ cd app/
$ composer install
$ cd public/
$ php -S 0.0.0.0:8000To disable caching and enable debugging, create a app/config/local.php file with the following:
<?php
define('CACHING_ENABLED', false);
define('DEBUG', true);Without cache, the website might be slow because of the inclusion of remote files (through HTTP). You can disable that
locally by adding this to your local.php:
define('DISABLE_INCLUDE', true);- Execute
./generate.sh - Commit
- Push
or just execute ./generateAndPush.sh.
The documents will be generated into the docs/generated directory. It will always generated the documentations for the master as well as for the latest stable version.
Just edit the docs/*.md files. Any change you make there should be available on the developer website within a minute.
Guides are written using Markdown. CommonMark and Markdown Extra are supported.
In addition:
- headers have an autogenerated HTML ID (so that they can be linked to). You can also use Markdown Extra to explicitly define it:
## Some title {#some-title-id} - you can include remote files as-is using:
{@include http://example.com/file.xml}: the content is not escaped{@include escape http://example.com/file.xml}: the content will be escaped
Create a new Markdown file in docs/ and use YAML Front Matter to configure it:
---
category: Develop
---
# The title
Lorem ipsum…YAML Front Matter is YAML embedded at the top of Markdown files. It is commonly used to define metadata, and we use it to define several items:
category: the name of the category (Develop, Integrate, Design, API Reference)subGuides: allows you to define a list of sub-guides (will appear in the left sidebar)previous: allows you to define the previous guide (a link will be added at the end of the guide, it does not affect the sidebar)next: allows you to define the next guide (a link will be added at the end of the guide, it does not affect the sidebar)
A guide must be either added to a category menu or set as a "sub-guide" of another guide. It cannot be both (else it will appear twice in the left sidebar).
To add a guide to a category (i.e. it will appear in the left sidebar) edit the PHP class for the category (in app/helpers/Content/Category).
The following tags can be used in PHP docblocks so that they can be turned to links in the API referenceIm.
{@hook Request.dispatch} // link to Request.dispatch hook
{@hook Request.dispatch description text} // link to Request.dispatch hook with different link text
{@hook # description} // link to hooks page
Note: In constrast to @link we do not check whether a hook with the given name exists.
{@link Map} // class within this namespace
{@link Piwik\DataTable\Map} // full classname
{@link \Exception} // php internal class
{@link serialize()} // php internal function
{@link getKeyName()} // method within this class
{@link $myproperty} // property within this class
{@link INDEX_NB_UNIQ_VISITORS} // constant within this class, note: a link will be only generated if the constant has a long description
{@link Map::getKeyName()} // method from any class
{@link Map::$myproperty} // property from any class
{@link Piwik\Metrics::INDEX_NB_UNIQ_VISITORS} // constant from any class, note: a link will be only generated if the constant has a long description
{@link http://piwik.org} // http link
{@link https://piwik.org} // https link
{@link mailto:test} // mailto link
{@link Map Description Text} // class within this namespace
{@link Piwik\DataTable\Map Description Text} // full classname
{@link \Exception Description Text} // php internal class
{@link getKeyName() Description Text} // method within this class
{@link $myproperty Description Text} // property within this class
{@link Map::getKeyName() Description Text} // method from any class
{@link Map::$myproperty Description Text} // property from any class
{@link http://piwik.org Description Text} // http link
{@link https://piwik.org Description Text} // https link
{@link mailto:test Description Text} // mailto link