Enhance the Documentation¶
Want to help improve the Documentation?
The Akeneo PIM documentation uses reStructuredText as its markup language and Sphinx for building the output (HTML, PDF, ...).
We’re very interested in tutorials or cookbooks to explain how to customize the PIM to fit 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 submit 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 start 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 use 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:: html+php
<?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::
.. code-block:: yaml
# Configuration in YAML
.. code-block:: xml
<!-- Configuration in XML //-->
.. code-block:: php
// Configuration in PHP
The previous reST snippet renders as follows:
# Configuration in YAML
<!-- Configuration in XML //-->
// Configuration in PHP
The current list of supported formats is 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 |
Adding Links¶
To add links to other pages in the documents use the following syntax:
:doc:`/path/to/page`
Using the path and filename of the page without the extension, for example:
:doc:`/book/architecture`
:doc:`/bundles/FooBundle/installation`
The link text will be the main heading of the document linked to. You can also specify alternative text for the link:
:doc:`Le Lien </bundles/FooBundle/installation>`
You can also add links to the PHP documentation:
:phpclass:`SimpleXMLElement`
:phpmethod:`DateTime::createFromFormat`
:phpfunction:`iterator_to_array`