Contributing

Folder and Page Structure

Conductor Hat Propeller Beanie Engineer Hat

This page aims to describe the preferred general structure of how files (pages, images, downloads etc.) should be arranged and named, along with the preferred structure of the individual pages.

By being consistent with these, it will be a) a better user experience, and b) be easier to maintain the documentation.

reStructuredText Standards

Please ensure to follow the standards below when creating or updating documentation to ensure the look and feel of the website remains consistent.

Elements

The elements of the documentation fall into the following broad categories:

Folders

Folders follow the basic structure:

  • Folder name

    • index.rst

    • getting-started.rst or overview.rst

    • … .rst (as needed)

Every folder SHOULD have a ‘index.rst’ file which is the primary navigation point for the pages in the folder
There are exceptions to this rule, but use them carefully.

Every folder SHOULD have either a ‘getting-started.rst’ OR and ‘overview.rst’ file which is the second navigation point for the pages in the folder
There are exceptions to this rule (e.g. the Throttle options), but use them carefully.

Pages

Pages generally follow the basic structure:

Meta Keywords

The meta keywords help search entries find find the page based on key words.

By using the recommended includes (below) several key meta keywords are included in all pages. i.e. DCC-EX DCC DCC++ EX DCC++EX Generally each page should start with any additional meta keywords that are appropriate to the page.

For example, the meta tags for levels.rst are:

Example

.. meta::
:keywords: Comfort Levels Conductor Tinkerer Engineer

Includes

All pages MUST include two standard include files. /include/include.rst and, depending on the depth in the folder structure, one of following as the second file:

  • /include/include-l0.rst

  • /include/include-l1.rst

  • /include/include-l2.rst

  • /include/include-l3.rst

For example:

Example

.. include:: /include/include.rst
.. include:: /include/include-l2.rst
.. include:: /include/include-description.rst

Note

The ‘include-description.rst’ will add a generic HTML meta description to the page. You can alternately make use of one the the other include files,or create a new one, to have different description for the page.

Product Icon

If the page specifically, and only, relates to one of the DCC-EX products, then specify the product icon immediately after include files, by using the appropriate expansion:

For example:

Example

.. include:: /include/include.rst
.. include:: /include/include-l3.rst
.. include:: /include/include-description.rst
|EX-CS-LOGO|

***************************************

Page Heading

Each page must have a Main Heading. Main Headings MUST have asterisks above and below them:

Example

*************
Main Heading
*************

See below for more information about heading.

Comfort level logos

On our Choose Your Comfort Level page, we refer to Conductor, Tinkerer, and Engineer level users, and where possible, we should be using these logos to help users understand what level the documentation is targeted at.

There are two types of logos available, one suitable for callouts or panels which are simply a square graphic, and one suitable for page headings that contains the graphic and the text.

  • Where possible, use the expansions for the level images:

    • |conductor| Conductor Hat

    • |tinkerer| Propeller Beanie

    • |engineer| Engineer Hat

    • |conductor-no-text| Conductor Hat

    • |tinkerer-no-text| Propeller Beanie

    • |engineer-no-text| Engineer Hat

  • Where possible, use the Team and Product names the expansions (not possible in headings)

    • |DCC-EX| for DCC-EX

    • |EX-CS| for EX‑CommandStation

    • |EX-I| for EX‑Installer

    • |EX-R| for EX‑RAIL

    • |EX-TT| for EX‑Turntable

    • |EX-DCCI| for EX‑DCCInspector

    • |BSC| for BaseStationClassic (DCC++)

  • Where possible, use the expansions for the level text

Only if really necessary use image tags:

.. image:: /_static/images/conductor.png
  :alt: Conductor Level
  :scale: 40%

.. image:: /_static/images/conductor-level.png
  :alt: Conductor Level
  :scale: 40%

Refer to Images below for details on how to include images, and set the scale as appropriate. A good example of the use of the different types of logos is the EX‑Turntable Assembly & Setup page.

On This Page - Table of Contents

Pages with multiple headings should generally have a Table of Contents. The depth of the table is a subjective decision.

.. sidebar::

  .. contents:: On this page
    :depth: 4
    :local:

Page Content

Page content can include:

After the heading, the page should start with an explanation of the purpose of the page.

Headings and Sub Headings

  • Main Headings have asterisks above and below them:

    ************
Main Heading
************

  • Subheadings are underlined with equals signs:

    Subheading
==========

  • The next level is underlined with hyphens:

    Next level
----------

  • And the next level is underlined with carets:

    Next level
^^^^^^^^^^

  • The next one we use is underlined with tildes:

    Next level
~~~~~~~~~~

  • The last one we use is underlined with underscores:

    Next level
__________

All heading underlines and overlines must be at least as long as the text of the heading text.

Text

Refer to the ReStructuredText Basics and Style Guide

Next steps - ReStucturedText Basics

Click next to learn how to enhance your content with links, tales, images, etc.