Skip to content

Latest commit

 

History

History
127 lines (92 loc) · 4.79 KB

README.md

File metadata and controls

127 lines (92 loc) · 4.79 KB
Raw

Piwik Developer Documentation

Documentations

License

GPLv3 or later

Run locally

$ cd app/
$ composer install
$ cd public/
$ php -S 0.0.0.0:8000

To 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);

Automatic documentation generation (API-Reference)

  • 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.

Writing guides

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

Adding a new guide

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).

Supported inline tags in PHP comments

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