Enhance the Documentation

Want to help to enhance the Documentation?

The Akeneo PIM documentation uses reStructuredText as its markup language and Sphinx for building the output (HTML, PDF, ...).

We’re very interested by tutorials or cookbook to explain how to customize the PIM to your project’s needs.

Before contributing on a new entry, please begin by creating an Issue on GitHub to explain your idea.

For typo / quick fixes you can directly propose a PullRequest.

To test the rendering of the documentation you can follow this HowTo.

reStructuredText

reStructuredText “is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system”.

You can learn more about its syntax by reading existing Akeneo PIM documents or by reading the reStructuredText Primer on the Sphinx website.

If you are familiar with Markdown, be careful as things are sometimes very similar but different:

  • Lists starts at the beginning of a line (no indentation is allowed);
  • Inline code blocks use double-ticks (``like this``).

Sphinx

Sphinx is a build system that adds some nice tools to create documentation from reStructuredText documents. As such, it adds new directives and interpreted text roles to standard reST markup.

Syntax Highlighting

All code examples uses PHP as the default highlighted language. You can change it with the code-block directive:

.. code-block:: yaml

{ foo: bar, bar: { foo: bar, bar: baz } }

If your PHP code begins with ``<?php``, then you need to use ``html+php`` as
the highlighted pseudo-language:

.. code-block:: rst

<?php echo $this->foobar(); ?>

Note

A list of supported languages is available on the Pygments website.

Configuration Blocks

Whenever you show a configuration, you must use the configuration-block directive to show the configuration in all supported configuration formats (PHP, YAML, and XML)

.. configuration-block::

# Configuration in YAML

<!-- Configuration in XML //-->

// Configuration in PHP

The previous reST snippet renders as follow:

# Configuration in YAML

<!-- Configuration in XML //-->

// Configuration in PHP

The current list of supported formats are the following:

Markup format Displayed
html HTML
xml XML
php PHP
yaml YAML
jinja Twig
html+jinja Twig
html+php PHP
ini INI
php-annotations Annotations