Folder and Page Structure
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.
Please ensure to follow the standards below when creating or updating documentation to ensure the look and feel of the website remains consistent.
The elements of the documentation fall into the following broad categories:
Image Artifacts / Original Grpahics (used to create the images, but not part of the documentation)
Folders follow the basic structure:
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 generally follow the basic structure:
Page Name (.rst file)
Product Icon (where appropriate)
On This Page - Table of Contents (on longer pages with multiple headings)
Description or purpose of the page
Text, links, images, etc.
Next Steps Heading (if it is part of sequence of pages this is mandatory)
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 DCC++ EX 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:
.. meta:: :keywords: Comfort Levels Conductor Tinkerer Engineer
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/include.rst .. include:: /include/include-l2.rst
The expansion must be followed by a blank line.
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:
.. include:: /include/include.rst .. include:: /include/include-l3.rst |EX-CS-LOGO| ***************************************
Each page must have a Main Heading. Main Headings MUST have asterisks above and below them:
************* 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:
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.
GitHub Issues Link
It is recommended to include links to the appropriate product’s GitHub issue templates by using the appropriate expansion on the same line as the comfort level expansions.
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 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:
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.
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.