Rules for editing pages¶

Warning

This page is under construction.

To contribute or participate contact support@boost-lab.net

Contents:

Page content
Navigation
Contents
Inline references
Index entries
Images naming convention
Videos
Keywords
Glossary
Section Author
Duplication of content
Figures and images

Page content ¶

After the title, the file includes the common text.

.. include:: /pages/common/pageunderconstruction.txt
        :start-line: 3

The page starts with a contents (see Contents). These are also included for each significant section. This provides a “what you are going to see”, and takes no maintenance.
Top of the page has a very light weight introduction that includes an overall picture with the location of the section indicated. The overall picture should be common (except for the highlights) across all the similar pages (e.g. same pic for AAM, ADPM, ADM, CTC, ParaMapping, AIM ARM…)
If necessary the next item is prerequisites, this could be links to other pages.
Ideallly the first item in a detail section is a video. These can be local or remote (e.g. youtube)
Subsequent sections do step-by-step using (if logical) screen grabs from the video
Use todo sections for areas that have been identified as needed, or quick notes on the steps that have yet to be written up properly.:
```
.. todo::

        the text, images etc that are work in progress
```

Contents ¶

The contents listing makes it easier to navigate up/down and also makes the RDT tree synchronise.

The contents should include backlinks.
It is prefereable to have a local contents at each significant section.
There is no rule for the depth but the preference is 1.

.. contents:: Contents:
        :local:
        :depth: 1
        :backlinks: top

Inline references ¶

The pages have a naming convention for the inline references (e.g. _how_DM_xxx) for (ease of maintenance);
These should be used (:ref:) instead of :doc: references, so that pages can be moved, renamed, split, consolidated without impacting other pages;
The top of page has top inline reference e.g. _how_DM_top. The build checks this is not used on other pages;

Index entries ¶

An index reference shall be added at the top of each page. The above example adds a “pair” of references for the page:
```
.. index:: :pair Domain Model; How To
```
This means the index can be used to find all the “How To” pages, and find all the pages wrt “Domain Model”
Other options see http://www.sphinx-doc.org/en/stable/markup/misc.html
- E.g. in text
- E.g. for subheadings such as .. index:: :pair Domain Model; Constraints
Note: “index:: :pair” is not always the best. Consideration should be taken over the collections in the index. The below files under “Activity Model” and “Mapping”, but not reciprocal entries:
```
.. index:: Activity Model; How to Map to Data Planning Model
.. index:: Mapping; How to - Activity Model to Data Planning Model
```

Figure 136 Illustration of result of the above paired index entries

Images naming convention ¶

The image name should include a shortened form of the location of the page, and the page itself (e.g. ht_aam_xxx.png). This prevents accidental overwrite.

Videos ¶

Include an index so all the videos can easily be located
Add a subheading so appears in contents
Record the video 1280x720 (widescreen 16:9) as this is then stored as HD in youtube
Copy the youtube Share:Embedded as raw:: html

Figure 137 What to copy from youtube

.. index:: Video; How to use a constraint in mapping

^^^^^
Video
^^^^^

.. raw:: html

        <iframe width="560" height="315" src="https://www.youtube.xxxx" frameborder="0" gesture="media" allowfullscreen></iframe>

Keywords ¶

There is a file in the source folder called keywords.rst. This contains key text that is replaced at build time. It is included at the end of each file.:

.. include:: /keywords.rst

This contains:

External references (make easer to maintain as all in one place) e.g.

.. |OMG SysML 1.4| replace:: `OMG Systems Modeling Language (OMG SysML) Version 1.4 <https://www.omg.org/spec/SysML/1.4/PDF>`__

Author names/emails (ease of maintenance e.g. when general support email changes) e.g.

.. |Judith Crockford| replace:: `Judith Crockford (AP243) <mailto:judith.crockford@airbus.com?subject=STEPLib Documentation>`__

Links to other Sphinx doc (we do not use the intersphinx capability because contributors environments may be different

.. |Git Index| replace:: `Git Documentation Index <http://cvs.boost-lab.net/sphinx/Git_Gitlab_User_Guide/html/index.html>`__

short cut names e.g. Application Activity Model

.. |AAM| replace:: Application Activity Model

Glossary ¶

The glossary is stored in the source/glossary.rst

Each term has an entry with the term, definition and links to major sections of the guide:

ADM
DM
        Application Domain Model

        See :doc:`Overview</pages/TheModelsOfTheStepArchitecture>`

        See :doc:`Description</pages/TheApplicationDomainModelOfAnAP>`

        See :doc:`How To</pages/howto/howtoDomainModel>`

The glossary is at the end of the table of contents before the index.
Glossary terms are automatically added to index

Glossary terms are used in the text with the :term:`xxx`

... defined in anyAP, with connected :term:`AAM`, :term:`ADPM`, :term:`ADM` and ...

Figure 138 What to copy from youtube

Section Author ¶

At a minimum each page should have a section author at the end using the keywords:

.. sectionauthor:: |Judith Crockford|

Section authors can also be added for each heading/subheading when there are more than one author per page.

Duplication of content ¶

There are cases it is more readable to duplicate content in multiple places rather than use hyperlinks.

To ease maintenance, this content should be stored in a separate text file and included.
The file should be .txt rather than .rst so that it is ignored as a file by the parser.

The file can contain content at the beginning which can then be ignored.

.. include:: /pages/common/pageunderconstruction.txt
        :start-line: 3

Figures and images ¶

All images should specify a scale, even if it is 100%. This automatically adds a click to open the image – and the M-R options of New Tab and New Window.

.. figure:: /images/common/comingsoon.png
        :scale: 100%

        Figure description

Section author: Judith Crockford (AP243)