CS-Cart Docs Author’s Guidelines

Introduction

The docs are written using the reStructuredText (reST) markup and built with Sphinx.

Please familiarize yourself with the reST specs and reStructuredText primer before contributing to the docs.

The ReST + Sphinx combo is a de-facto standard used in the Python world.

Refer to this page source as a live example.

Zen of Docs

  • A cool documentation is one which changes [1].
  • If you don’t understand it, nobody will.
  • Listen to your heart.
  • Cut out without worry.
  • Improve without delay.
  • Sparse is better than dense [2].
  • Overclarity is better than underclarity.
  • Formatting matters.

General

Sparse is better than dense, so, if you have a choice, always prefer inserting an empty line and indenting.

Use bold with prudence; bold text draws reader’s attention, and reader’s attention is a limited resource.

Italic is a more gentle way to highlight a statement; it should be used to indicate a different type of text (e.g. a path) rather than stress out the statement itself (this is the bold’s job).

Typography

Below you will find some typography standards adopted by the CS-Cart documentation.

Headers

The first header on a page is used as its title. It is marked with two lines or * (asterisk), one above and another below the line:

*************
War and Peace
*************

Important

All three lines must be equally long, otherwise the build will fail.

The same applies to all other headers described below.

First-level header is marked with an underline of = (the equality sign):

Chapter 1
=========

Second-level header is marked with an underline of - (dash):

At the Ball
-----------

It is not often that you will need to use a lower level header. If you absolutely must, use an underline of " (doublequote) for a third-level header:

Later that Evening
""""""""""""""""""

Note

If you need to go deeper, please reconsider this decision. It is usually better to split a doc into two instead of creating a single overnested monster.

Paths, URLs, and Code Samples

Paths

Paths must be marked up in italic:

/srv/http/cscart/

<some path>/my_file.ext

URLs

Keep URLs clean and tidy. Do not forget to place http at the beginning. Avoid www in URLs. Trailing slash is OK.

URLs must be marked up in italic:

https://cs-cart.com/

Code samples

PHP code can be inserted simply by using :: (double colon) and indenting the code below:

Here is some PHP code::

    $greeting = "Hello, World!";

    $twelve = 7 + 5;

To show a sample of code in another language, use the code-block directive with the language specified as its param:

Here is some Python code:

    .. code-block:: python

        def hello(name=None):
            if name:
                print('Hello, {name}!'.format(name=name))
            else:
                print('Hello, World!')

Read more about showing code examples in the Sphinx documentation.

Short code samples can be shown inline in fixed-width:

Value binding in Python is as simple as ``name = value``.

Notes, Importants, Warnings, and Hints

Sphinx supports a variety of information block directives, but only four are used in the CS-Cart docs: .. note::, .. important::, .. warning::, and .. hint::.

Note

Use this directive to show an additional piece of information, which can be safely skipped while reading, but will be useful as general knowledge:

And this is how you bake a cake.

.. note::

    Cakes are extremely popular in Ireland.

Renders to:

Note

Cakes are extremely popular in Ireland.

Important

Use this directive to show a block of important information that is should not be skipped:

Set the permissions to **777**.

.. important::

    The installation will fail if the persmissions are incorrect.

Renders to:

Important

The installation will fail if the persmissions are incorrect.

Warning

This directive should be used with caution. It indicates a dangerous turn in the narrative:

Now your store is ready for the upgrade.

.. warning::

    All existing data will be lost!

Renders to:

Warning

All existing data will be lost!

Hint

This directive is not used too often. Use it to point to a useful tool or tip:

Copy the new files to your directory.

.. hint::

    You can use `Ctrl + C` to copy files and `Ctrl + V` to paste them.

Renders to:

Hint

You can use Ctrl + C to copy files and Ctrl + V to paste them.

Images

Images are inserted with the .. image:: directive:

.. image:: img/cscart.png
    :align: center
    :alt: CS-Cart logo

Always set the :align: param to center and define the :alt: param.

Footnotes

[1]Based on Cool URIs don’t change by Tim Berners-Lee
[2]From Zen of Python