TSC Sphinx Doc Manual V4.0

TSC Sphinx Extension User Manual
ID: tsc_sphinx_doc_manual
Version: V4.0
Status: Published
Author: Alexandre Betis
Date: 28/07/2022
Review: !960
Authorized by: Alexandre Betis
Configuration Management
Commit: 396671d2
Document signature
05a0a6b4abdd927fe30de7643a36765158c9b1bc
CONTENTS
1 Revision history [artifact history] 3
2 Introduction 4
3 Getting started 6
4 Installation 8
5 Training ground 11
6 Basic documentation 12
7 Generalities 30
8 Artifacts 33
9 Configuration items 40
10 Product Breakdown Structure 43
11 Parts 44
12 Requirements 47
13 Functions 53
14 RAMS 57
15 Roles and activities 59
16 Software & Tools 62
17 Verification and Testing 63
18 Quality Assurance 70
19 Utilities 71
20 Building documentation 73
21 Spell checking 76
22 Experimental features 77
23 Directives reference 78
Index 100
2 of 101 CONTENTS
CHAPTER
ONE
REVISION HISTORY [ARTIFACT HISTORY]
This artifact version is: V4.0
This artifact signature: 05a0a6b4abdd927fe30de7643a36765158c9b1bc
Name Description Date Author Signature MR

2627091b3d0111a86af25
DRAFTV0 Draft version released for training purposes 12/12/2021 Alexandre Betis !632
fdb190444e403a0bc7e
9fcf5fbf87fac5d90d527
V1 First version of the manual 20/01/2022 Alexandre Betis !632
be88a6f85022a304158
"Add new directives to assign artifacts to 112303f47f589cc0df8b1
V1.1 01/02/2022 Alexandre Betis !644
configuration items." ce28fff27212d01148f
e9871495ee730cee04f7f
V2 "Add new directives for PBS and parts." 23/03/2022 Alexandre Betis !649
dad1ff5c88cb19e6ceb
5991e70df4d7e999d35eb
V2.1 "Add autodoc features for tests." 15/06/2022 Alexandre Betis !855
838bb1ce025828f7124
"Add QA dashboard. Add mode and base- f6b09846153f8f2bfd43e
line directives." 5fdb3bc3cfd8ae7d96f
97c924bfdb44754d470fb
V3.0 Add documentation for baseline support 13/07/2022 Alexandre Betis !605
a5514cc637a2446b6a1
Update for V1.2. Document RAMS direc- 05a0a6b4abdd927fe30de
tives 7643a36765158c9b1bc
1. Revision history [artifact history] 3 of 101

CHAPTER
TWO
INTRODUCTION
2.1 Context
Within the context of its iEVC project, TSC developed the TSC Sphinx tool in order to manage the complex
technical documentation tool generated by this project.
2.2 Purpose
The purpose of this manual is to provide the necessary knowledge to use the TSC Sphinx tool.
2.3 Contents
The document is structured as follows:

• Introduction. This chapter;
• Getting started provides quick start instructions;
• Installation provides the installation instructions;
• Training ground explains how to access the training environment, where one can experiment the tools’
features;
• Basic documentation explains how to write basic documentation;
• Generalities explains the basics of TSC directives in general;
• Artifacts explains how to declare documents and various types of artifacts in the documentation;
• Configuration items explains how to declare configuration items and manage the resulting product structure;
• Product Breakdown Structure explains how to build product breakdown structures;
• Parts explains how to declare and manage parts;
• Requirements explains how to declare and manage requirements;
• Functions explains how to declare and manage functions;
• RAMS explains how to declare and manage hazards and maintain the related hazard logs;
• Roles and activities explains how to declare activities and build responsibility matrices;
• Software & Tools explains how to document software;
• Verification and Testing explains how to document verification activities;
• Utilities provides information on some utility directives;
• Building documentation recapitulates the different formats that can be used to present the documentation
(HTML, PDF, JSON, . . . )
4 of 101 2. Introduction
• Spell checking describes the spell checking features;

• Experimental features describes experimental features;
• Finally, Directives reference contains the full reference of all the possible commands (a.k.a. “directives”)
available;
2.4 Applicable documents
[TSC-SPHINX-MANUAL-R0-GLOSSARY] TSC glossary [id: glossary]

[TSC-SPHINX-MANUAL-R1-RMP] TSC Product Requirement Management Policy [id:
tsc_quality_doc_policy_rm]
[TSC-SPHINX-MANUAL-R2-CMP] TSC Product Configuration Management Policy [id:
tsc_quality_doc_policy_cm]
[TSC-SPHINX-MANUAL-R3-SPHINXRS] TSC Sphinx Requirement Specification [id: tsc_sphinx_doc_spec]
2.5 Reference documents
[TSC-SPHINX-MANUAL-R3-ARCADIA] Model-based System and Architecture Engineering with the Arcadia

Method, Jean-Luc Voirin, 1st Edition - November 22, 2017
[TSC-SPHINX-MANUAL-R4-MATH] Short Math Guide for LaTeX, Michael Downes, updated by Barbara Bee-
ton, American Mathematical Society, Version 2.0 - December 22, 2017.
2.6 Terms and definition
Refer to [TSC-SPHINX-MANUAL-R0-GLOSSARY] .
2.7 Artifact definition
Artifact
TSC Sphinx Extension User Manual [artifact]
2.4. Applicable documents 5 of 101

CHAPTER
THREE
GETTING STARTED
Sphinx is a tool for that simplifies the production and maintenance of a technical documentation.
Sphinx is able to generate the documentation in html and latex format. It can also perform a spelling check of the
content.
It was originally created for the Python documentation, and it has excellent facilities for the documentation of
software projects in a range of languages.
The TSC Sphinx extension extends the capability of Sphinx with the ability to manage systems engineering topics
such as:
• Requirements management
• Configuration management
• Documentation versioning
Furthermore, the TSC Sphinx extension is able to extract a JSON database of items of interest from the documen-
tation.
Sphinx uses reStructuredText as its markup language. It is a text-based markup language were items of interests
are identified using directives. These are simple keywords, prefixed with .. and suffixed with ::. The TSC
extension defines additional directives that enrich this markup language. For example, it defines a tsc_req
directive that can be used in the documentation to document a requirement:
A long time ago in a galaxy far far away...
.. tsc_req:: The text shall be displayed in blue over black background

:id: STARWARS_INTRO_REQ_1
The root directory of a Sphinx documentation contains two files:

• A root document, named index.rst. The main function of the root document is to serve as a welcome
page, and to contain the root of the “table of contents tree” (or toctree). This is one of the main things that
Sphinx adds to reStructuredText, a way to connect multiple files to a single hierarchy of documents.
• The Sphinx configuration file conf.py, where you can configure all aspects of how Sphinx reads your
sources and builds your documentation.
The toctree directive initially is empty, and looks like so:
.. toctree::
:maxdepth: 1
Note: More on directives

toctree is a reStructuredText directive, a very versatile piece of markup. Directives can have arguments, options
and content.
Arguments are given directly after the double colon following the directive’s name. Each directive decides whether
it can have arguments, and how many.
6 of 101 3. Getting started

Options are given after the arguments, in form of a “field list”. The maxdepth is such an option for the toctree
directive.
Content follows the options or arguments after a blank line. Each directive decides whether to allow content, and
what to do with it.
A common gotcha with directives is that the first line of the content must be indented to the same level as the
options are.
The main purpose of the TSC Sphinx extension is to provide additional directives.
You add documents listing them in the content of the directive:
.. toctree::
:maxdepth: 1
doc_structure
installation
training
This is exactly how the toctree for this documentation looks. The documents to include are given as document
names, which in short means that you leave off the file name extension and use forward slashes (/) as directory
separators.
You can now create the files you listed in the toctree and add content, and their section titles will be inserted
(up to the maxdepth level) at the place where the toctree directive is placed. Also, Sphinx now knows about
the order and hierarchy of your documents. (They may contain toctree directives themselves, which means
you can create deeply nested hierarchies if necessary.)
7 of 101
CHAPTER
FOUR
INSTALLATION
The TSC Sphinx extension is delivered as an integral part of the iEVC source code.
4.1 Pre-requisites
You will need to type command in a command prompt.

If you are a Linux user, it is a given.
Under Windows, to find it, the quickest way is to click on the Windows search tool, and type ‘cmd’ in the search
bar. You should see a ‘Command Prompt App’ appear. Click ‘run as administrator’.
You will need some familiarity about how to navigate in the folders using the ‘cd’ command, and launch basic
commands.
You will need download a copy of the TSC repository using GIT. Basic knowledge of GIT is assumed, and it is
assumed that GIT is installed on your machine.
Important: Some of the features of the TSC Sphinx extension assume that the documentation is under GIT
source control.
To check if Git is installed on your machine, open a command prompt and type the following command:
git --version
The version number should be displayed, for instance:
git version 2.21.0.windows.1
Note: Git can be tedious to operate if you have to type your gitlab username and password for each
pull/push/clone.
Username and password typing issue can be solved by configuring SSH keys to be used, as explained here:
https://docs.gitlab.com/ee/gitlab-basics/create-your-ssh-keys.html
Sphinx is a tool developed in Python. It is assumed that Python3 is installed on your machine.
To check if Python3 is installed on your machine, open a command prompt and type the following command:
python --version
The version number should be displayed, starting with 3. For instance:
Python 3.9.6
8 of 101 4. Installation
4.2 On Linux
A Linux (e.g. Ubuntu 64 bits) running Python3 is required.

Clone the last version of the tsc repository:
git clone https://gitlab.com/tsc-projects/tsc.git
Install the python packages:
pip install -r requirements.txt
Install the dependencies on Alpine Linux:
sudo apt install make cmake enchant aspell-en texlive texmf-dist texmf-dist-
˓→latexextra zip
Install the dependencies on Ubuntu 18.04:
sudo apt install make cmake aspell-en texlive texlive-binaries texlive-extra-utils

˓→zip latexmk texlive-science texlive-formats-extra
Note: In the TSC repository, look into the file .gitlab-ci.yml for the up-to-date list of dependencies. The
tsc_docker directory provides a working environment based on docker.
We use CMake as our build tool. To run it:
cmake .
make
The full build not only builds HTML, Latex, PDF and JSON doc, but it also looks for spelling mistakes and broken
links in the doc.
If you want to just generate the doc in HTML:
make tsc_doc_html
Other possible targets include:

• tsc_json
• tsc_doc_latex
• tsc_doc_pdf
Note: In the TSC repository, look into the file, look into the CMake configuration file CMakeLists.txt to know all
available targets.
The build targets are produced in a _build directory. In order to reset the build:
make clean
4.2. On Linux 9 of 101

4.3 On Windows
In order to use all the above on Windows, follow the following steps.
1. If you plan on generating documentation in PDF, install TexLive: https://tug.org/texlive/acquire-netinstall.
html. If you are happy with only HTML and other formats, skip this step. You can do it later.
Note: More specifically, download and run this http://mirror.ctan.org/systems/texlive/tlnet/install-tl-windows.

exe. Plan a few liters of coffee, that takes a bunch of time.
2. After that, ensure that you have Python installed, version 3.8.X or newer. If not, download from https:
//www.python.org/downloads/
Note: Make sure to uninstall previous python versions before installing the new one
Ensure that the python installation directory is simple (like c:/python) and not too complicated a path. Ideally, it
should be accessible on the command line directly.
3. Ensure that you have git for Windows installed (from https://git-scm.com/download/win)
4. run the following command:
git config --global core.autocrlf false
5. Clone the last version of the tsc repository:
git clone https://gitlab.com/tsc-projects/tsc.git
6. Install all python build tools as follows:
cd tsc
pip install -r .\requirements.txt
7. Test your windows build installation:
make_html.bat
Important: The windows scripts must be run as Administrator. The scripts will emit a suitable warning in case
it is not done.
8. To clean:
make_clean.bat
9. To build the JSON export of the documentation:
make_json.bat
10. To build the PDF documentation:
make_pdf.bat
Warning: Building the doc in PDF is actually a multiple stage process. First, a JSON version is built, then
latex, then PDF. Refer to Building documentation, for an in-depth explanation.
10 of 101 4.3. On Windows

CHAPTER
FIVE
TRAINING GROUND
The iEVC source code contains a properly configured root directory with an empty documentation. The folder is:
tsc_sphinx/training/. The folder contains also the same windows .bat files that can be used to build
the documentation in a Windows environment.
This empty documentation can be used for training purposes.
Under Windows, to generate the training documentation, starting from the root of the iEVC source code:
cd tsc_sphinx
cd tsc_training
.\make_html.bat
Under Linux, use the sphinx-build command directly to generate your documentation:
cd tsc_sphinx
cd tsc_training
sphinx-build -b html . _build/doc/html
The result should look as shown in the following figure.
5. Training ground 11 of 101

CHAPTER
SIX
BASIC DOCUMENTATION
reStructuredText (reST) is the default plain text markup language used by Sphinx. This language was initially
developed as part of the Docutils project.
Docutils provides the basic reStructuredText syntax, while Sphinx extends this to support additional functionality.
Finally, the TSC Sphinx extension adds yet additional functionality.
This section provides the basics of reStructuredText for writing documentation. It is a compressed version of the
equivalent section in the Sphinx reference documentation.
It does not cover the TSC-specific extensions.
6.1 Quick run
6.1.1 Hello world
To get started, this is an example of what a minimal Sphinx document looks like:
===========
Hello World
===========
Titles are identified with an underline repeating a

character like '=', '-', '*'.
Paragraphs are simply blocks of texts separated by a

white line.
Chapter 1
*********
This will be a chapter in the document
Chapter 1.1
###########
This will be a sub-section of chapter 1.
Chapter 2
*********
This will be another chapter. Sphinx knows

that because we used the same character to
underline the title.
12 of 101 6. Basic documentation

6.1.2 Roles
A role or “custom interpreted text role” (role) is an inline piece of explicit markup. It signifies that the enclosed
text should be interpreted in a specific way.
Roles are introduced between two ‘:’, and the text to interpret follows between two ‘`’.
This will look like this:
This role makes :strong:`this appears in bold`
Some roles are so common, there is a short cut. For instance:
**This appears in bold too**
*This will appear in italics*
The most useful roles are presented in Inline markup (a.k.a. roles) below, while the Sphinx roles documentation
provides the full list.
6.1.3 Directives
Directives can be used to highlight a very large range of items of interest in the text. This is used heavily by the
Sphinx and the TSC extension (for example, to highlight requirements, activities, artifacts, etc).
A directive is a generic block of explicit markup. Along with roles, it is one of the extension mechanisms of reST,
and Sphinx makes heavy use of it.
Basically, a directive consists of a name, arguments, options and content (keep this terminology in mind, it is used
in the next chapters describing custom directives). Let’s look at this example,
.. function:: foo(x)
foo(y, z)
:module: some.module.name
Return a line of text input from the user.
function is the directive name. It is given two arguments here, the remainder of the first line and the second
line, as well as one option module (as you can see, options are given in the lines immediately following the
arguments and indicated by the colons). Options must be indented to the same level as the directive content.
The directive content follows after a blank line and is indented relative to the directive start or if options are
present, by the same amount as the options.
Be careful as the indent is not a fixed number of whitespace, e.g. three, but any number whitespace. This can be
surprising when a fixed indent is used throughout the document and can make a difference for directives which
are sensitive to whitespace. Compare:
.. code-block::
:caption: A cool example
The output of this line starts with four spaces.
.. code-block::
The output of this line has no spaces at the beginning.
In the first code block, the indent for the content was fixated by the option line to three spaces, consequently the
content starts with four spaces. In the latter the indent was fixed by the content itself to seven spaces, thus it does
not start with a space.
Sphinx adds additional directives. This document presents the most useful ones.
6.1. Quick run 13 of 101

6.2 Paragraphs
The paragraph is the most basic block in a reST document. Paragraphs are simply chunks of text separated by one
or more blank lines. As in Python, indentation is significant in reST, so all lines of the same paragraph must be
left-aligned to the same level of indentation.
6.3 Inline markup
The standard reST inline markup is quite simple: use

• one asterisk: *text* for emphasis (italics),
• two asterisks: **text** for strong emphasis (boldface), and
• back quotes: ``text`` for code samples.
If asterisks or back quotes appear in running text and could be confused with inline markup delimiters, they have
to be escaped with a backslash.
Be aware of some restrictions of this markup:
• it may not be nested,
• content may not start or end with whitespace: * text* is wrong,
• it must be separated from surrounding text by non-word characters. Use a backslash escaped space to work
around that: thisis\ *one*\ word.
These restrictions may be lifted in future versions of the docutils.
It is also possible to replace or expand upon some of this inline markup with roles. Refer to Inline markup (a.k.a.
roles) for more information.
6.4 Lists and Quote-like blocks
List markup is natural: just place an asterisk at the start of a paragraph and indent properly. The same goes for
numbered lists; they can also be auto-numbered using a # sign:
* This is a bulleted list.

* It has two items, the second
item uses two lines.
1. This is a numbered list.

2. It has two items too.
#. This is a numbered list.

#. It has two items too.
Nested lists are possible, but be aware that they must be separated from the parent list items by blank lines:
* this is
* a list
* with a nested list

* and some subitems
* and here the parent list continues
Definition lists are created as follows:
14 of 101 6.2. Paragraphs

term (up to a line of text)

Definition of the term, which must be indented
and can even consist of multiple paragraphs
next term
Description.
Note that the term cannot have more than one line of text.
Quoted paragraphs are created by just indenting them more than the surrounding paragraphs.
6.5 Literal blocks
Literal code blocks are introduced by ending a paragraph with the special marker ::. The literal block must be
indented (and, like all paragraphs, separated from the surrounding ones by blank lines):
This is a normal text paragraph. The next paragraph is a code sample::
It is not processed in any way, except

that the indentation is removed.
It can span multiple lines.
This is a normal text paragraph again.
The handling of the :: marker is smart:

• If it occurs as a paragraph of its own, that paragraph is completely left out of the document.
• If it is preceded by whitespace, the marker is removed.
• If it is preceded by non-whitespace, the marker is replaced by a single colon.
That way, the second sentence in the above example’s first paragraph would be rendered as “The next paragraph
is a code sample:”.
Code highlighting can be enabled for these literal blocks on a document-wide basis using the highlight direc-
tive and on a project-wide basis using the highlight_language configuration option. The code-block
directive can be used to set highlighting on a block-by-block basis. These directives are discussed later.
6.6 Tables
6.6.1 List tables
The recommended way to declare tables is to use List tables.

Each table has the number of columns and their associated relative widths indicated in a width tag.
For proper formatting, the asterisk indicating each row must align vertically, and the hyphens indicating each
column must also align. Empty cells must be accounted for, so that each column in a row is always marked, even
if there is no content in the table cell. An example of an empty cell is the second column in the first row of the
following example.
.. list-table:: Title
:widths: 25 25 50
:header-rows: 1
* - Heading row 1, column 1

(continues on next page)
6.5. Literal blocks 15 of 101

(continued from previous page)

- Heading row 1, column 2
- Heading row 1, column 3
* - Row 1, column 1
-
- Row 1, column 3
* - Row 2, column 1
- Row 2, column 2
- Row 2, column 3
This table is displayed as:
Table 6.1: Title

Heading row 1, column Heading row 1, column Heading row 1, column 3
1 2
Row 1, column 1 Row 1, column 3
Row 2, column 1 Row 2, column 2 Row 2, column 3
6.6.2 CSV tables
It’s often easier to create tables in a program like Excel than with RST syntax. You can then save the table as a
CSV file, and reference the CSV file in your RST file where you want the table to go.
When you have a CSV file, reference it with the .. csv-table:: directive. For widths, use the percentage
width of each column (without the % sign). For header rows, typically use 1.
Make sure the parameters match the content of the CSV file.
.. csv-table:: Table Title

:file: CSV file path and name
:widths: 30, 70
:header-rows: 1
Within the CSV file, you can use RST markup just as you would if writing in directly in the RST file.
6.6.3 Long tables
Some tables may be very long and span multiple pages when generating the documentation in a paginated format
such as PDF. In this case, it is necessary to use the class option and set it to the value longtable as in the
following example. This instructs the builders to split the table over multiple pages.
.. csv-table:: Long Table Title

:file: Big CSV file path and name
:widths: 30, 70
:header-rows: 1
:class: longtable
16 of 101 6.6. Tables

6.6.4 Other formats
It is also possible to use grid tables (grid-tables) and simple tables (simple-tables).
6.7 Hyperlinks
6.7.1 External links
Use `Link text <https://domain.invalid/>`_ for inline web links. If the link text should be the
web address, you don’t need special markup at all, the parser finds links and mail addresses in ordinary text.
Important: There must be a space between the link text and the opening < for the URL.
6.7.2 Internal links
Internal linking is done via a special reST role provided by Sphinx, see the section on specific markup, Cross-
referencing arbitrary locations.
6.8 Sections
Section headers (sections) are created by underlining (and optionally overlining) the section title with a punctua-
tion character, at least as long as the text:
=================
This is a heading
=================
Normally, there are no heading levels assigned to certain characters as the structure is determined from the suc-
cession of headings. However, this convention is used in Python’s Style Guide for documenting which you may
follow:
• # with overline, for parts
• * with overline, for chapters
• =, for sections
• -, for subsections
• ^, for sub subsections
• ", for paragraphs
Of course, you are free to use your own marker characters (see the reST documentation), and use a deeper nesting
level, but keep in mind that most target formats (HTML, LaTeX) have a limited supported nesting depth.
6.7. Hyperlinks 17 of 101

6.9 Inline markup (a.k.a. roles)
A role or “custom interpreted text role” (role) is an inline piece of explicit markup. It signifies that the enclosed
text should be interpreted in a specific way. Sphinx uses this to provide semantic markup and cross-referencing of
identifiers, as described in the appropriate section. The general syntax is :rolename:`content`.
Docutils supports the following roles:
• emphasis – equivalent of *emphasis*
• strong – equivalent of **strong**
• literal – equivalent of ``literal``
• subscript – subscript text
• superscript – superscript text
• title-reference – for titles of books, periodicals, and other materials
Sphinx adds additional roles. We present here the most useful ones.
6.9.1 Cross-referencing arbitrary locations
:ref:
To support cross-referencing to arbitrary locations in any document, the standard reST labels are used. For
this to work label names must be unique throughout the entire documentation. There are two ways in which
you can refer to labels:
• If you place a label directly before a section title, you can reference to it with :ref:`label-name`.
For example:
.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.
The :ref: role would then generate a link to the section, with the link title being “Section to cross-
reference”. This works just as well when section and reference are in different source files.
Automatic labels also work with figures. For example:
.. _my-figure:
.. figure:: whatever
Figure caption
In this case, a reference :ref:`my-figure` would insert a reference to the figure with link text
“Figure caption”.
The same works for tables that are given an explicit caption using the table directive.
• Labels that aren’t placed before a section title can still be referenced, but you must give the link an
explicit title, using this syntax: :ref:`Link title <label-name>`.
Note: Reference labels must start with an underscore. When referencing a label, the underscore must be
omitted (see examples above).
18 of 101 6.9. Inline markup (a.k.a. roles)

Using ref is advised over standard reStructuredText links to sections (like `Section title`_) be-
cause it works across files, when section headings are changed, will raise warnings if incorrect, and works
for all builders that support cross-references.
6.9.2 Cross-referencing documents
There is also a way to directly link to documents:

:doc:
Link to the specified document; the document name can be specified in absolute or relative fashion. For
example, if the reference :doc:`parrot` occurs in the document sketches/index, then the link
refers to sketches/parrot. If the reference is :doc:`/people` or :doc:`../people`, the
link refers to people.
If no explicit link text is given (like usual: :doc:`Monty Python members </people>`), the link
caption will be the title of the given document.
6.9.3 Cross-referencing figures by figure number
:numref:
Link to the specified figures, tables, code-blocks and sections; the standard reST labels are used. When you
use this role, it will insert a reference to the figure with link text by its figure number like “Fig. 1.1”.
If an explicit link text is given (as usual: :numref:Ìmage of Sphinx (Fig. %s)
<my-figure>`), the link caption will serve as title of the reference. As placeholders, %s and {num-
ber} get replaced by the figure number and {name} by the figure caption. If no explicit link text is given, the
numfig_format setting is used as fall-back default.
If numfig is False, figures are not numbered, so this role inserts not a reference but the label or the link
text.
6.9.4 Referencing terms in the glossary
:term:
Reference to a term in a glossary. A glossary is created using the glossary directive containing a defini-
tion list with terms and definitions. It does not have to be in the same file as the term markup, for example
the Python docs have one global glossary in the glossary.rst file.
If you use a term that’s not explained in a glossary, you’ll get a warning during build.
6.9.5 Math
:math:
Role for inline math. Use like this:
Since Pythagoras, we know that :math:à^2 + b^2 = c^2`.
Refer to the math directive documentation for more information about the math syntax.
6.9. Inline markup (a.k.a. roles) 19 of 101

6.10 Table of contents

.. toctree::
This directive inserts a “Table of content (TOC) tree” at the current location, using the individual TOCs
(including “sub-TOC trees”) of the documents given in the directive body. Relative document names (not
beginning with a slash) are relative to the document the directive occurs in, absolute names are relative to the
source directory. A numeric maxdepth option may be given to indicate the depth of the tree; by default,
all levels are included.
The representation of “TOC tree” is changed in each output format. The builders that output multiple files
(ex. HTML) treat it as a collection of hyperlinks. On the other hand, the builders that output a single file
(ex. LaTeX, man page, etc.) replace it with the content of the documents on the TOC tree.
Consider this example (taken from the Python docs’ library reference index):
.. toctree::
:maxdepth: 2
intro
strings
datatypes
numeric
(many more documents listed here)
This accomplishes two things:

• Tables of contents from all those documents are inserted, with a maximum depth of two, that means
one nested heading. toctree directives in those documents are also taken into account.
• Sphinx knows the relative order of the documents intro, strings and so forth, and it knows that
they are children of the shown document, the library index. From this information it generates “next
chapter”, “previous chapter” and “parent chapter” links.
Entries
Document titles in the toctree will be automatically read from the title of the referenced document. If that
isn’t what you want, you can specify an explicit title and target using a similar syntax to reST hyperlinks.
This looks like:
.. toctree::
intro
All about strings <strings>
datatypes
The second line above will link to the strings document, but will use the title “All about strings” instead
of the title of the strings document.
You can also add external links, by giving an HTTP URL instead of a document name.
Section numbering
If you want to have section numbers even in HTML output, give the toplevel toctree a numbered option.
For example:
.. toctree::
:numbered:
foo
bar
Numbering then starts at the heading of foo. Sub-toctrees are automatically numbered (don’t give the
numbered flag to those).
Numbering up to a specific depth is also possible, by giving the depth as a numeric argument to numbered.
20 of 101 6.10. Table of contents

Additional options
You can use the caption option to provide a toctree caption and you can use the name option to provide
an implicit target name that can be referenced by using ref:
.. toctree::
:caption: Table of Contents
:name: mastertoc
foo
If you want only the titles of documents in the tree to show up, not other headings of the same level, you
can use the titlesonly option:
.. toctree::
:titlesonly:
foo
bar
You can use “globbing” in toctree directives, by giving the glob flag option. All entries are then matched
against the list of available documents, and matches are inserted into the list alphabetically. Example:
.. toctree::
:glob:
intro*
recipe/*
*
This includes first all documents whose names start with intro, then all documents in the recipe folder,
then all remaining documents (except the one containing the directive, of course.)
The special entry name self stands for the document containing the toctree directive. This is useful if you
want to generate a “sitemap” from the toctree.
You can use the reversed flag option to reverse the order of the entries in the list. This can be useful
when using the glob flag option to reverse the ordering of the files. Example:
.. toctree::
:glob:
:reversed:
recipe/*
You can also give a “hidden” option to the directive, like this:
.. toctree::
:hidden:
doc_1
doc_2
This will still notify Sphinx of the document hierarchy, but not insert links into the document at the location
of the directive – this makes sense if you intend to insert these links yourself, in a different style, or in the
HTML sidebar.
In cases where you want to have only one top-level toctree and hide all other lower level toctrees you can
add the includehidden option to the top-level toctree entry:
.. toctree::
:includehidden:
6.10. Table of contents 21 of 101


doc_1
doc_2
All other toctree entries can then be eliminated by the “hidden” option.
In the end, all documents in the source directory (or sub-directories) must occur in some toctree directive;
Sphinx will emit a warning if it finds a file that is not included, because that means that this file will not be
reachable through standard navigation.
Use exclude_patterns in your configuration file to explicitly exclude documents or directories from
building completely.
The “root document” (selected by the root_doc option in the configuration file) is the “root” of the TOC
tree hierarchy. It can be used as the documentation’s main page, or as a “full table of contents” if you don’t
give a maxdepth option.
6.11 Admonitions, warnings, notes
Admonitions are used to highlight messages in the text. In most themes, these are rendered as colored boxes. This
is an example of warning admonition directive:
.. warning:: Look out! A three-headed monkey
It is rendered as follows:
Warning: Look out! A three-headed monkey
The possible admonitions are attention, caution, danger, error, hint, important, note, tip,
warning and the generic admonition. Most themes style only “note” and “warning” specially.
6.12 Inserting images
6.12.1 Images
.. image::
This directive inserts an image with a label.
The URI for the image source file is specified in the directive argument. For example:
.. image:: picture.jpeg
:height: 100px
:width: 200 px
:scale: 50 %
:alt: alternate text
:align: right
The following options are recognized:

alt [text] Alternate text: a short description of the image, displayed by applications that cannot display
images, or spoken by applications for visually impaired users.
height [length (in px or cm)] The desired height of the image. Used to reserve space or scale the image
vertically. When the “scale” option is also specified, they are combined. For example, a height of
200px and a scale of 50 is equivalent to a height of 100px with no scale.
22 of 101 6.11. Admonitions, warnings, notes

width [length (in px or cm) or percentage of the current line width] The width of the image. Used to
reserve space or scale the image horizontally. As with “height” above, when the “scale” option is also
specified, they are combined.
scale [integer percentage (the “%” symbol is optional)] The uniform scaling factor of the image. The
default is “100 %”, i.e. no scaling.
align [“top”, “middle”, “bottom”, “left”, “center”, or “right”] The alignment of the image, equivalent to
the HTML <img> tag’s deprecated “align” attribute or the corresponding “vertical-align” and “text-
align” CSS properties. The values “top”, “middle”, and “bottom” control an image’s vertical alignment
(relative to the text baseline); they are only useful for inline images (substitutions). The values “left”,
“center”, and “right” control an image’s horizontal alignment, allowing the image to float and have the
text flow around it. The specific behavior depends upon the browser or rendering software used.
target [text (URI or reference name)] Makes the image into a hyperlink reference (“clickable”). The
option argument may be a URI (relative or absolute), or a reference name with underscore suffix (e.g.
à name`_).
When used within Sphinx, the file name given (here picture.jpeg) must either be relative to the source file, or
absolute which means that they are relative to the top source directory. For example, the file sketch/spam.rst
could refer to the image images/spam.png as ../images/spam.png or /images/spam.png.
Sphinx will automatically copy image files over to a sub-directory of the output directory on building (e.g. the
_static directory for HTML output.)
Interpretation of image size options (width and height) is as follows: if the size has no unit or the unit is pixels,
the given size will only be respected for output channels that support pixels. Other units (like pt for points) will
be used for HTML and LaTeX output (the latter replaces pt by bp as this is the TeX unit such that 72bp=1in).
Sphinx extends the standard docutils behavior by allowing an asterisk for the extension:
.. image:: gnu.*
Sphinx then searches for all images matching the provided pattern and determines their type. Each builder then
chooses the best image out of these candidates. For instance, if the file name gnu.* was given and two files
gnu.pdf and gnu.png existed in the source tree, the LaTeX builder would choose the former, while the HTML
builder would prefer the latter.
Note: Image file names should not contain spaces.
6.12.2 Figures
.. figure::
A “figure” consists of image data (including image options), an optional caption (a single paragraph), and
an optional legend (arbitrary body elements). For page-based output media, figures might float to a different
position if this helps the page layout.
.. figure:: picture.png
:scale: 50 %
:alt: map to buried treasure
This is the caption of the figure (a simple paragraph).
The legend consists of all elements after the caption. In this

case, the legend consists of this paragraph and the following
table:
+-----------------------+-----------------------+
| Symbol | Meaning |
+=======================+=======================+
6.12. Inserting images 23 of 101


| .. image:: tent.png | Campground |
+-----------------------+-----------------------+
| .. image:: waves.png | Lake |
+-----------------------+-----------------------+
| .. image:: peak.png | Mountain |
+-----------------------+-----------------------+
There must be blank lines before the caption paragraph and before the legend. To specify a legend without
a caption, use an empty comment (“..”) in place of the caption.
The “figure” directive supports all of the options of the “image” directive (see Images above). These options
(except “align”) are passed on to the contained image.
align [“left”, “center”, or “right”] The horizontal alignment of the figure, allowing the image to float and
have the text flow around it. The specific behavior depends upon the browser or rendering software
used.
In addition, the following options are recognized:
figwidth [“image”, length, or percentage of current line] width The width of the figure. Limits the
horizontal space used by the figure. A special value of “image” is allowed, in which case the included
image’s actual width is used. If the image file is not found or the required software is unavailable, this
option is ignored.
Sets the “width” attribute of the “figure” directive element.
This option does not scale the included image; use the “width” option for that.
+---------------------------+
| figure |
| |
|<------ figwidth --------->|
| |
| +---------------------+ |
| | image | |
| | | |
| |<--- width --------->| |
| +---------------------+ |
| |
|The figure's caption should|
|wrap at this width. |
+---------------------------+
6.13 Including files
There are two ways to include files.

.. include:: filename
This includes a file as if it were additional reST content.
For instance:
And thus spoke Zarathustra:
.. include:: zarathustra.rst
.. literalinclude:: filename
This includes a file as if it were a code sample to be included literally. Use the language option to specify
the language. If Sphinx is able to parse the language, it will highlight the syntax accordingly. Use the
linenos option to display the line numbers.
This is an example:
24 of 101 6.13. Including files

The code looks like this:
.. literalinclude:: code.c
:language: c
:linenos:
There are multiple possible options, that are documented in the Sphinx documentation here.
.. only:: <expression>
Include the content of the directive only if the expression is true. The expression should consist of tags, like
this:
.. only:: html and draft
Undefined tags are false, defined tags (via the -t command-line option or within conf.py) are true.
Boolean expressions, also using parentheses (like html and (latex or draft)) are supported.
The format and the name of the current builder (html, latex or text) are always set as a tag. To
make the distinction between format and name explicit, they are also added with the prefix format_ and
builder_, e.g. the epub builder defines the tags html, epub, format_html and builder_epub.
These standard tags are set after the configuration file is read, so they are not available there.
All tags must follow the standard Python identifier syntax as set out in the Identifiers and keywords docu-
mentation. That is, a tag expression may only consist of tags that conform to the syntax of Python variables.
In ASCII, this consists of the uppercase and lowercase letters A through Z, the underscore _ and, except for
the first character, the digits 0 through 9.
Warning: This directive is designed to control only content of document. It could not control sections,
labels and so on.
6.14 Showing code examples

.. code-block:: [language]
Example:
.. code-block:: ruby
Some Ruby code.
The directive’s alias name sourcecode works as well. This directive takes a language name as an ar-
gument. It can be any lexer alias supported by Pygments. If it is not given, the setting of highlight
directive will be used. If not set, highlight_language will be used.
options
:linenos: (no value)

Enable to generate line numbers for the code block:
:linenos:
Some more Ruby code.
:lineno-start: number (number)

Set the first line number of the code block. If present, linenos option is also automatically activated:
6.14. Showing code examples 25 of 101

:lineno-start: 10
Some more Ruby code, with line numbering starting at 10.
:emphasize-lines: line numbers (comma separated numbers)

Emphasize particular lines of the code block:
.. code-block:: python
:emphasize-lines: 3,5
def some_function():
interesting = False
print 'This line is highlighted.'
print 'This one is not...'
print '...but this one is.'
:caption: caption of code block (text)

Set a caption to the code block.
:name: a label for hyperlink (text)
Define implicit target name that can be referenced by using ref. For example:
.. code-block:: python
:caption: this.py
:name: this-py
print 'Explicit is better than implicit.'
In order to cross-reference a code-block using either the ref or the numref role, it is necessary that
both name and caption be defined. The argument of name can then be given to numref to generate
the cross-reference. Example:
See :numref:`this-py` for an example.
When using ref, it is possible to generate a cross-reference with only name defined, provided an
explicit title is given. Example:
See :ref:`this code snippet <this-py>` for an example.
:dedent: number (number or no value)

Strip indentation characters from the code block. When number given, leading N characters are re-
moved. When no argument given, leading spaces are removed via textwrap.dedent(). For
example:
:dedent: 4
some ruby code
:force: (no value)

If given, minor errors on highlighting are ignored.
26 of 101 6.14. Showing code examples

6.15 Glossary
.. glossary::
This directive must contain a reST definition-list-like markup with terms and definitions. The definitions
will then be referenceable with the term role. Example:
.. glossary::
environment
A structure where information about all documents under the root is
saved, and used for cross-referencing. The environment is pickled
after the parsing stage, so that successive runs only need to read
and parse new and changed documents.
source directory
The directory which, including its subdirectories, contains all
source files for one Sphinx project.
In contrast to regular definition lists, multiple terms per entry are allowed, and inline markup is allowed in
terms. You can link to all of the terms. For example:
.. glossary::
term 1
term 2
Definition of both terms.
(When the glossary is sorted, the first term determines the sort order.)
If you want to specify “grouping key” for general index entries, you can put a “key” as “term : key”. For
example:
.. glossary::
term 1 : A
term 2 : B
Definition of both terms.
Note that “key” is used for grouping key as is. The “key” isn’t normalized; key “A” and “a” become
different groups. The whole characters in “key” is used instead of a first character; it is used for “Combining
Character Sequence” and “Surrogate Pairs” grouping key.
In i18n situation, you can specify “localized term : key” even if original text only have “term” part. In this
case, translated “localized term” will be categorized in “key” group.
6.16 Math
The input language for mathematics is LaTeX markup. This is the generally accepted standard for plain-text math
notation and has the added advantage that no further translation is necessary when building LaTeX output.
For a guide to LaTeX math, the reader may refer to [TSC-SPHINX-MANUAL-R4-MATH].
.. math::
Directive for displayed math (math that takes the whole line for itself).
The directive supports multiple equations, which should be separated by a blank line:
.. math::
(a + b)^2 = a^2 + 2ab + b^2

6.15. Glossary 27 of 101

(a - b)^2 = a^2 - 2ab + b^2
In addition, each single equation is set within a split environment, which means that you can have mul-
tiple aligned lines in an equation, aligned at & and separated by \\:
.. math::
(a + b)^2 &= (a + b)(a + b) \\

&= a^2 + 2ab + b^2
When the math is only one line of text, it can also be given as a directive argument:
.. math:: (a + b)^2 = a^2 + 2ab + b^2
Normally, equations are not numbered. If you want your equation to get a number, use the label option.
When given, it selects an internal label for the equation, by which it can be cross-referenced, and causes an
equation number to be issued. See eq for an example. The numbering style depends on the output format.
There is also an option nowrap that prevents any wrapping of the given math in a math environment. When
you give this option, you must make sure yourself that the math is properly set up. For example:
.. math::
:nowrap:
\begin{eqnarray}
y & = & ax^2 + bx + c \\
f(x) & = & x^2 + 2xy + y^2
\end{eqnarray}
6.17 Footnotes
For footnotes (footnotes), use [#name]_ to mark the footnote location, and add the footnote body at the bottom
of the document after a “Footnotes” rubric heading, like so:
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
.. rubric:: Footnotes
.. [#f1] Text of the first footnote.

.. [#f2] Text of the second footnote.
You can also explicitly number the footnotes ([1]_) or use auto-numbered footnotes without names ([#]_).
6.18 Citations
Standard reST citations are supported, with the additional feature that they are “global”, i.e. all citations can be
referenced from all files. Use them like so:
Lorem ipsum [Ref]_ dolor sit amet.
.. [Ref] Book or article reference, URL or whatever.
Important: The citations are global. Therefore, use different identifiers in each reST source file to avoid refer-
encing citations from another document.
28 of 101 6.17. Footnotes

This is bad:
My document
===========
.. [R1] First reference

.. [R2] Second reference
This is good:
My document
===========
.. [MYDOC-R1] First reference

.. [MYDOC-R2] Second reference
Citation usage is similar to footnote usage, but with a label that is not numeric or begins with #.
6.19 Substitutions
reST supports “substitutions”, which are pieces of text and/or markup referred to in the text by |name|. They
are defined like footnotes with explicit markup blocks, like this:
.. |name| replace:: replacement *text*
or this:
.. |caution| image:: warning.png

:alt: Warning!
If you want to use some substitutions for all documents, put them into rst_prolog or rst_epilog or put
them into a separate file and include it into all documents you want to use them in, using the include directive.
(Be sure to give the include file a file name extension differing from that of other source files, to avoid Sphinx
finding it as a standalone document.)
6.20 Comments
Every explicit markup block which isn’t a valid markup construct (like the footnotes above) is regarded as a
comment. For example:
.. This is a comment.
You can indent text after a comment start to form multi-line comments:
..
This whole indented block
is a comment.
Still in the comment.
6.19. Substitutions 29 of 101

CHAPTER
SEVEN
GENERALITIES
All TSC-specific directives start with the tsc_ prefix.

The Directives reference section contains the technical reference for each directive. The following sections intro-
duce important options and concepts that are shared by all TSC directives.
7.1 Directive identifiers
When you use a TSC directive, the data of the directives (e.g. its argument and options) is captured in a database
in memory, where each type of directive correspond to a table of data.
As an example, if you declare a requirement using the tsc_req directive, like this:
.. tsc_req:: There shall be light

:id: REQ_LIGHT
The data of the directive is captured as a row in a table containing all the requirements declared in the documen-
tation.
In this database, Sphinx will automatically create a unique identifier for each TSC directive declared. This identi-
fier will start by the identifier of the directive, followed by a unique identification string.
The identifier string is directive dependent. For most directives, it is built from the argument itself. For some
others it is built from an explicit id field (this is the case for requirements).
Important: Sphinx guarantees unicity of identifiers. If you attempt to create two directives with identical
identifiers, an error will be generated.
In our example, the identifier will be tsc-req-req-light.
Note: Identifiers all start with the name of the directives, are lower-cased and hyphenated. This type of identifier
is known as a Slug. Such identifiers can be used for various technical purposes such as printing or defining web
links related to the directive.
When reporting errors, Sphinx will mention the identifier of the offending directive, as well as the document name
and line number.
It is possible to dump the database of all directives in a JSON format. See tsc_json. This is extremely useful to
perform qualitative analysis on the documentation content.
30 of 101 7. Generalities
7.2 Standard rendering
By default, TSC directive declarations are rendered in boxes. The boxes are split in two sections: a header and a
body. The header contains the directive argument, while the body contains the directive’s body.
The header contains two sub-boxes.
• The Data box contains the directive meta-data.
• The Referenced by box lists all the places where the directive is referenced. This is useful to follow, for
example, traceability links between requirements.
When rendered, the directive argument is post-fixed with a minimal set of meta-data. This allows to spot the
declarations when they are not rendered the standard ways.
In HTML, Data and Referenced by boxes are rendered as buttons. Click on these buttons to read the data. It is
possible to hide these boxes completely by clicking on the “hide all” button that is on the upper right corner of the
screen.
In Latex / PDF, only a subset of Data boxes are rendered. This is defined statically for each directive type. Refer
to Directives reference.
7.3 Cross-referencing
:tsc:
This role provides an inline cross-reference to any arbitrary tsc directive definition. The string should be
composed of the name of the directive (without the tsc_ prefix), a column (‘:’) and the directive argument
or identifier.
This is an example:
.. tsc_role:: Bryan
Where is :tsc:`role:Bryan`?
7.4 Referencing artifacts
:tsc_artifact:
This role provides an inline cross-reference to an artifact. In HTML, the role is rendered as an hyperlink
to the corresponding HTML page, while in PDF, if possible, the role is rendered as an hyperlink to corre-
sponding PDF.
The tsc_artifact role should be used when citing artifacts. For example.
Plan for world domination

=========================
Reference documents
-------------------
.. [PLAN-WORLD-R1] The Prince, by Machiavel
.. [PLAN-WORLD-R2] :tsc_artifact:`Casino Royale Business Plan`
Note: The version of the artifact is not shown by the role. The reason behind this decision is that if we show the
version, then we will have to change all referencing document version every time a document takes a new version.
This is simply not manageable.
7.2. Standard rendering 31 of 101

7.5 Hiding the directive
You can use the :hidden: option to hide the directive from the rendered document. What happens is that the
directive content is inserted as a comment in the generated documentation.
For example:
.. tsc_role:: Ninja
:hidden:
Important: Hidden directive data is still captured. Only the rendering is commented out.
7.6 Rendering as paragraph
Sometimes it is better to render directives as a simple paragraph, and remove all the meta data. This is achieved
by using the as_paragraph option, like this:
.. tsc_role:: Declaration rendered as a paragraph

:as_paragraph:
7.7 Rendering as section
It is possible to render directive declarations as a section of the document. Use the as_section option. This is
an example:
.. tsc_role:: Declaration rendered as section

:as_section:
32 of 101 7.5. Hiding the directive

CHAPTER
EIGHT
ARTIFACTS
Artifacts represents the result of an activity. Typical artifacts are documents, data files, or software code.
Note: Relevant directives: tsc_artifact, tsc_artifact_status, tsc_artifact_version, tsc_artifact_history
8.1 Artifact types
The main challenge of managing artifacts is to keep track of where artifacts are stored, as well as their various
versions.
Important: This is a very difficult thing to do with a large number of artifacts being constantly updated by a herd
of contributors. The directives presented here were designed with the goal of ensuring that no modification could
go unnoticed, and to ensure that artifacts are stored in a controlled way.
There are four different categories of artifact to manage:

• External artifacts: these are documents or material that is accessible outside of TSC. An example of such
artifact is a standard or an article of law;
• Sphinx artifacts: these are documents generated using Sphinx.
• Generic artifacts: these special types of artifacts represent a kind of artifact. For example, we can declare a
generic artifact for user manuals. Such artifacts are useful for example to describe activities. See Roles and
activities.
• Software artifacts: these are software binary files or data files.
The following sections explain how to manage each type of artifact.
To specify the type of each artifact, use the type option. The possible options are:
• Doc
• Software
• Model
• Excel
• Software Package
.. tsc_artifact:: Wish list

:type: Excel
8. Artifacts 33 of 101
8.2 External artifacts
To declare such an artifact, use the tsc_artifact directive.
.. tsc_artifact:: Plan for world domination
An external artifact must be stored somewhere. If you declare an artifact as above, Sphinx will generate a warning
like this:
WARNING: Could not resolve access path for artifact tsc-artifact-plan-for-world-

˓→domination.
You can specify where to find an artifact using the base_url, path and filename options. This is useful if
you want to reference artifacts that are external to those produced by the considered project (e.g. standards, texts
of law, etc).

:base_url: https://www.spectre.org/
:path: blofeld
:filename: plan.html
Every declared artifact has a status option. By default, the status is ‘Planned’, meaning that the artifact is
planned to be produced but is not yet available. The two other options possible are ‘Review’ and ‘Published’. The
purpose of this status will be discussed further in Publishing Sphinx artifacts. In the case of an external artifact,
the status should logically be Published.

:base_url: https://www.spectre.org/
:path: blofeld
:filename: plan.html
:status: Published
Note: Based on this declaration, Sphinx will try to guess the MIME type of the file. You can force the mime type
using the mime option.
If you observe the generated documentation in HTML, you will notice that a ‘[Link]’ hyperlink has been added
next to the title of the artifact. This link points to the address obtained from the concatenation of the base_url,
path and filename documented for the artifact.
Note: In the above example, the link will be: https://www.spectre.org/blofeld/plan.html
You can document the version of an external artifact, using the following options. These options accept any text
as input.
• current_version_name: the name of the version (e.g. ‘V1’)
• current_version_author: the author of the version (e.g. ‘Le Chiffre’)
• current_version_date: the date of the version (e.g. ‘07/07/2007’)
• current_version_authorizer: the person having authorized the artifact (e.g. ‘Ernst Stavro
Blofeld’)
34 of 101 8.2. External artifacts

8.3 Sphinx artifacts
To declare an artifact generated using Sphinx, use the tsc_artifact directive with the source and docname
option.
The sources of an artifact are all the files (reST and others) that are required to compile the artifact using Sphinx.
From these source files, Sphinx will calculate a numerical signature that will uniquely identify a given version of
the artifact.
Important: It is crucial to list all the files that are used to compile the document. When displaying figures, for
example, you need to include the figures’ image files in the list.
After documentation is generated, the data section of the artifact declaration will contain the calculated signature.
The docname is the name of the sphinx document that you want to use as the root for generating a corresponding
PDF document. Let us take the example of the TSC Sphinx directive reference document:
.. tsc_artifact:: TSC Sphinx directives reference

:source: tsc_sphinx/docs/directives.rst
:sphinx_docname: tsc_sphinx_doc/directives
The source files are specified relative to a tsc_src_dir configuration option in the conf.py file.
The sphinx docname is given relative to the root document. It is the name of the reST file, without the .rst
extension.
8.4 Generic artifacts
To declare a generic artifact, use the tsc_artifact directive with the generic option.
.. tsc_artifact:: User manuals

:generic:
You can then declare other artifacts as concrete instances of a given generic artifact. For instance:
.. tsc_artifact:: TSC Sphinx User Manual

:instance_of: User manuals
This can be used to ensure that all the generic artifacts planned in the various plans are instantiated properly
somewhere in the documentation.
8.5 Software artifacts
To declare a software artifact, use the tsc_artifact directive with the source and type option.
The source should specify where to find the various software files to consider. You may use glob patterns when
specifying the source.
Set the type option to Software.
For example:
.. tsc_artifact:: DOOM
:source: doom/src/*.c,
doom/include/*.h
:type: Software
8.3. Sphinx artifacts 35 of 101

A numerical signature will be computed on the source files. In addition, the source files will be zipped in a file
bearing the name of the artifact and its current version will be created. It can be accessed by the ‘[Link]’ hyperlink.
8.6 Versioning artifacts
In order to document the version of a declared artifact, use the tsc_artifact_version directive. This
directive does not take any argument but has three mandatory options:
• artifact: The name of the artifact.
• name: The name of the version. This is free text. Examples: ‘V1’, ‘DRAFTV1’;
• date: The date of the version. This is free text. No formatting check is done.
In addition, the following options should be documented:
• author: The author of the version. This is free text.
• authorizer: The authorizer of the version. This is free text.
• description: The description of the version. This is free text.
• mr: Merge request identifier. It is assumed by Sphinx that a revision control system is in place to control the
changes in the source files of the artifact. Therefore, the review of changes leading to a new version should
be documented in a suitable Merge request (Gitlab terminology) or Pull request (GitHub terminology).
Finally, remember that Sphinx computes a unique numerical signature for its artifacts. By documenting the
signature field with this signature, it is possible to tie the documented version to a specific version of the
artifact.
Note: After documentation is generated, the data section of the artifact declaration contains the calculated
signature. This signature should be used to populate the signature field.
This is an example of documenting a version of an artifact:
.. tsc_artifact_version::
:name: V1
:date: 2006
:artifact: Plan for world domination
:author: Le Chiffre
:authorizer: Ernst Stavro Blofeld
:description: Add proposed Poker game at Casino Royal
:signature: 123456780
.. tsc_artifact_version::
:name: V2
:date: 2008
:artifact: Plan for world domination
:author: Dominic Green
:authorizer: Ernst Stavro Blofeld
:description: Hoard water in the Bolivian desert
:signature: 987654321
Sphinx uses the signature data to determine if the current version of the artifact is documented.
If the version is documented, it uses this knowledge to automatically determine the value of the
current_version_name of the artifact. If the signature of the artifact corresponds to none of those doc-
umented in a tsc_artifact_version declared for the artifact, then current_version_name takes the
value ‘DRAFT’.
36 of 101 8.6. Versioning artifacts

Important: In other words, if you make any change to the source of an artifact, it becomes a draft. This is the
whole purpose of this mechanism.
8.7 Where to document artifact versions
The astute reader will have noticed that it is not possible to document the version of artifacts in the artifact source
code itself. Indeed, the signature is computed on the source, so, if we write the signature in the source, the
signature is modified, leading to a never-ending draft state:
source -> signature A -> update source with signature A -> signature B -> ...
Therefore, artifact versions should be documented in reST files alongside the actual content files. For instance in
a version.rst file.
Note: It is also possible to document version in a tabular file (Excel or CSV), and import the data. Refer to
Importing directives from Excel.
8.8 Documenting the revision history
Use the tsc_artifact_history directive to insert the revision history of an artifact in the documentation.
In the generated documentation, all documented versions will be recapitulated in a table.
The directive displays also the current version of the artifact, based on its signature and documented version. The
current signature is also documented.
.. tsc_artifact_history:: Revision history of this file

:artifact: TSC Sphinx extension user manual
:as_section:
Note: It is customary to display artifact revision history as a section.
It is convenient to have an hyperlink to the MR appear in the table. To achieve this, it is necessary to specify in
the conf.py file what is the URL of the gitlab or GitHub server, using the tsc_mr_url option.
8.9 Publishing Sphinx artifacts
Use the status option of artifacts to determine the publication status of an artifact.
There are three possible status:
• The default status is ‘Planned’. It corresponds to artifacts that are in draft and are not supposed to be
published;
• The status ‘Review’ identifies the artifacts that should be published only for review;
• Finally, the status ‘Published’ identifies those artifacts that have been authorized to be published;
It is assumed that an automated process will pick this status to determine if a PDF should be generated for each
artifact.
8.7. Where to document artifact versions 37 of 101

Note: What follows illustrates what happens in the case of the iEVC project.
Typically:
• This is done in the conf.py
• This depends on the GIT branch you are working on
If you are working on a master branch, then automated process will generate the PDF for all published artifacts.
If there are published artifacts in draft, then this will result into an error.
Important: The key requirement is that no artifact should be published in draft.
If you are working on a non-master branch, then automated process should generate the PDF only for artifacts in
review and published artifacts in draft.
Note: This avoids generating the entire documentation on non-master branch, as this takes some time.
Finally, the automated process should pick the generated PDF and copy them over to a secure storage (the Library).
The library URL can be documented in the conf.py file using the tsc_library_url configuration option.
This option is used by Sphinx to generate hyperlinks to published artifacts in the HTML documentation.
It is possible to specify the publication status of artifacts aside the artifact declaration, using the
tsc_artifact_status directive.
.. tsc_artifact_status::
:artifact: TSC Sphinx extension user manual
:status: Published
8.10 Phase
It is possible to specify a typical project phase for each artifact. Use the phase option. The possible options are:
• 0 - Planning
• 1 - Concept
• 2 - System Definition & Operational Context
• 3 - Risk Analysis And Evaluation
• 4 - Specification Of System Requirements
• 5 - Architecture & Apportionment Of System
• 6 - Design & Implementation
• 7 - Manufacture
• Safety
• Feasibility
38 of 101 8.10. Phase

8.11 ISA ranking
It is possible to specify if the document is to be systematically inspected by an independent safety assessor (ISA)
or upon request only.
Set the isa_ranking option to “Primary” if the document should be systematically inspected by the ISA.
Default value is “Secondary”.
8.12 Requirements
It is possible to specify requirements that are applicable to an artifact. Use the requirements option for that
and refer to Requirements to use this feature for requirement tracing purposes.
8.11. ISA ranking 39 of 101

CHAPTER
NINE
CONFIGURATION ITEMS
Sphinx offers numerous directives to support the TSC configuration management policy (refer to
[TSC-SPHINX-MANUAL-R2-CMP]). The reader should refer to this policy for a conceptual introduction.
Note: Relevant directives: tsc_ci, tsc_baseline, tsc_ci_artifact, tsc_ci_component, tsc_artifact_list
9.1 Configuration items
To declare a CI, use the tsc_ci directive, providing a name as argument.

.. tsc_ci:: Vinegar
It is possible to compose CIs together.

.. tsc_ci:: Oil
.. tsc_ci:: Vinegar
.. tsc_ci:: Vinaigrette
:composed_of: Oil, Vinegar
Sometimes it is not possible to document the components of a CI where the CI is declared. In this case, use the
tsc_ci_component directive to add components to a CI.
.. tsc_ci:: Salt and Pepper
.. tsc_ci_component::
:ci: Vinaigrette
:component: Salt and Pepper
Use the code option to assign a code to the CI.
Important: The CI identifier is not based on the code but on the CI name itself. The idea being to be able to
change the code of CIs without breaking all the references in the documentation.
.. tsc_ci:: Oil
:code: V.OIL
.. tsc_ci:: Vinegar
:code: V.VINEGAR
:composed_of: Oil, Vinegar
:code: V
40 of 101 9. Configuration items

9.2 Documenting artifacts for configuration items
Artifacts may be linked to configuration items. This is the way to go in order to prepare a documentation list for a
given configuration item.
To add an artifact to a configuration item, either document it directly in the artifacts option of the CI, or use
the tsc_ci_artifact directive.
.. tsc_artifact:: Recipe for vinaigrette
.. tsc_artifact:: Sticker for the bottle
:artifacts: Recipe for vinaigrette
.. tsc_ci_artifact:: Add the sticker for the bottle of

vinaigrette
:ci: Vinaigrette
:artifact: Sticker for the bottle
You may specify multiple configuration items or artifacts in the tsc_ci_artifact directive.
.. tsc_ci_artifact:: Add usual specs to master Bruce's things.

:ci: Batmobile,
Batwing,
Batsuite
:artifact: Black paint reference,
Bullet proof specifications
The directive will add all the specified artifacts to all listed CIs.
9.3 Listing artifacts
To list the artifacts for a given configuration item, use the tsc_artifact_list directive.
.. tsc_artifact_list:: Vinaigrette documentation list

:ci: Vinaigrette
This directive will generate the list of all artifacts under the specified configuration items, with all their informa-
tion.
The directive automatically generates an Excel sheet listing the artifacts. This sheet can be downloaded from a
‘[Click Here to Download]’ hyperlink in HTML. In PDF, the Excel sheet is embedded in the file, and can be
downloaded by clicking on the paperclip icon next to the directive header.
You may specify the excel_only option to only generate the Excel sheet and not display the list in the docu-
ment.
9.4 Baselines
To document a baseline for a configuration, use the tsc_baseline directive. The directive will compute
a numerical signature on the configuration item by concatenation of the signatures of each and every artifact
attached to the CI.
This process is repeated recursively for the sub configuration items composing the CI.
.. tsc_baseline:: Vinaigrette recipe

:ci: Vinaigrette
9.2. Documenting artifacts for configuration items 41 of 101

To actually lock a baseline in configuration, document the signature using the signature option. Once this is
done, any modification to the artifacts of the baseline will be reported as an error during the build.
You may specify a name for the baseline using the name option.
To document limitations on a baseline, use the tsc_limitation directive. The limitation must receive a
unique identifier (using the id option), and be assigned to a CI (using the ci option).
For example:
.. code-block:: RST
.. tsc_limitation:: Do not use lemon

:ci: Vinaigrette
:id: no-lemon
42 of 101 9.4. Baselines

CHAPTER
TEN
PRODUCT BREAKDOWN STRUCTURE
It is possible to present a CI structure in the form of a product breakdown structure (PBS).
Note: Relevant directives: tsc_pbs
To display a PBS, use the tsc_pbs directive.
.. tsc_pbs:: PBS of the Saturn 5 rocket

:ci: Saturn 5 rocket
The argument should be a unique name for the PBS. The ci option is mandatory, and should specify the CI for
which we generate the PBS.
In HTML, the directive will generate two representation:
• A tree view, that can be folded and unfolded to navigate the PBS. For each node in the tree view, the
following information is provided:
– The CI data;
– Links to the artifacts that have been assigned to the CI;
– Links to the parts that have been declared to instantiate the CI;
• An HTML table that recapitulates important data about the CI.
In order to represent the hierarchy of CI in a tabular fashion, the directive calculates for each row in the table a
hierarchical identification string (e.g. “1.1.3.2”), as well as a depth number.
Furthermore, the directive shall generate an Excel version of the PBS. This sheet can be downloaded from a ‘[Click
Here to Download]’ hyperlink in HTML. In PDF, the Excel sheet is embedded in the file, and can be downloaded
by clicking on the paperclip icon next to the directive header.
The tree view is only shown in HTML, while the table appears in other formats such as PDF.
ment.
You may specify the excel_only_in_html option to hide the table in HTML, but still show it in other
formats.
You may specify the hide_navigator option to hide HTML tree view.
10. Product Breakdown Structure 43 of 101

CHAPTER
ELEVEN
PARTS
A part materializes a design instance of a configuration item. It is uniquely identified by a part number and can
be ordered.
Note: Relevant directives: tsc_part, tsc_sub_part_data, tsc_part_list, tsc_supplier
11.1 Declaring parts
To declare a part, use the tsc_part directive. For each part, it is mandatory to specify the following options:
• part_number: in order to uniquely identify the part;
• supplier: in order to identify the supplier of the part;
Suppliers must be declared using the tsc_supplier directive.
.. tsc_supplier:: ACME
.. tsc_part:: ACME Dynamite

:supplier: ACME
:part_number: TNT-BOOM-123
A part may be an instance of a configuration item. In that case, use the ci option to document this relationship.
Note: Once this is done, the part will appear in any PBS where the CI appears. See Product Breakdown Structure.
11.2 Documenting parts data
The following options are available to document the part (option names are self-explanatory)
• height_mm
• width_mm
• depth_mm
• length_mm
• weight_kg
• power_watt
• power_input
44 of 101 11. Parts

.. tsc_part:: Anaconda
:supplier: Nature
:part_number: BIG.SNAKE
:length_mm: 12000
Note: Depending on the type of part declared, the option may be appropriate or not.
11.3 Declaring part documentation
It is possible to declare certain artifact versions as supporting documents for a part. The following supporting
documents are expected:
• Datasheets - Use the datasheet option
• Manuals - Use the manual option
• CAD models. These are 3D files that can be used in CAD tools to integrate the part in a larger drawing. -
Use the cad_model option
• Certification kit - Use the certification_kit option
• Baseline - Use the baseline option. This is especially important to document parts that represent a given
version of a software;
.. tsc_part:: ACME Rocket

:supplier: ACME
:part_number: ROCKET-BOOM-123
:datasheet: ACME Rocket Datasheet V1
:manual: ACME Rocket User Manual V4
Important: Parts are documented using precise versions of artifacts.
11.4 Managing sub-parts
It is possible to declare sub parts of a part, therefore building a hierarchy of parts. To declare a sub-part, use the
sub_parts option.
.. tsc_part:: ACME Rocket

:supplier: ACME
:part_number: ROCKET-BOOM-123
:sub_parts: ACME Rocket Head,
ACME Rocket Tank,
ACME Rocket Engine
By default, it is assumed that there a part contains one instance of each sub part. Where this is not the case, use
the tsc_sub_part_data directive.
This directive takes no argument, but requires that a part and a sub_part option be documented. Use the
quantity option to define the quantity of sub-part that the part must contain. The info option can be used to
provide contextual information.
.. tsc_part_data::
:part: ACME Rocket
:sub_part: ACME Rocket Engine
11.3. Declaring part documentation 45 of 101


:quantity: 3
:info: More engine, more speed!
11.5 Parts lists
To display a parts list, use the tsc_part_list directive.
.. tsc_part_list:: ACME Rocket BOQ

:part: ACME Rocket
The argument should be a unique name for the part list. The part option is mandatory, and should specify the
part for which we generate the list.
In HTML, the directive will generate two representation:
• A tree view, that can be folded and unfolded to navigate the part list. For each node in the tree view, the
following information is provided:
– The part data;
– Links to the part documentation;
• An HTML table that recapitulates important data about the parts.
In order to represent the hierarchy of parts in a tabular fashion, the directive calculates for each row in the table a
hierarchical identification string (e.g. “1.1.3.2”), as well as a depth number.
Furthermore, the directive shall generate an Excel version of the part list. This sheet can be downloaded from
a ‘[Click Here to Download]’ hyperlink in HTML. In PDF, the Excel sheet is embedded in the file, and can be
downloaded by clicking on the paperclip icon next to the directive header.
The tree view is only shown in HTML, while the table appears in other formats such as PDF.
ment.
You may specify the excel_only_in_html option to hide the table in HTML, but still show it in other
formats.
You may specify the hide_navigator option to hide HTML tree view.
46 of 101 11.5. Parts lists

CHAPTER
TWELVE
REQUIREMENTS
Sphinx offers numerous directives to support the TSC requirements management policy (refer to
[TSC-SPHINX-MANUAL-R1-RMP]). The reader should refer to this policy for a conceptual introduction to
the management of requirement.
Note: Relevant directives: tsc_req, tsc_stakeholder, tsc_allocate, tsc_req_spec, tsc_req_list,

tsc_req_traceability_matrix
12.1 Declaring requirements
To declare a requirement use the tsc_req directive. It is mandatory to provide an identifier using the id option.
Note: There is no formatting imposed on the id. It is plain text.
Important: Sphinx will guarantee the unicity of the requirement ID.
For instance:
.. tsc_req:: Sphinx docs shall be gorgious

:id: REQ_SPHINX_GORGIOUS
It is possible to write more precise description of the requirements in the body of the directive.

Gorgious meaning that people will *want* to use the tool after
looking at the resulting documentation.
Important: It is not recommended to include external references or directives in the body of a requirement
declaration. Sphinx will emit some informational warning when this is done. The reason is that requirements are
supposed to be atomic pieces of information. Refer to [TSC-SPHINX-MANUAL-R1-RMP].
12. Requirements 47 of 101

12.2 Traceability
Use the source option to declare the source requirement of a requirement. Additionally, use the
source_justification option to justify this traceability.
.. tsc_req:: Have a noble goal in life

:id: REQ_NOBLE_GOAL
.. tsc_req:: Sphinx docs shall be georgious

:id: REQ_SPHINX_GEORGIOUS
:source: REQ_NOBLE_GOAL
:source_justification: That is a noble goal to have.
12.3 Stakeholders
Use the tsc_stakeholder directive to declare stakeholders.
.. tsc_stakeholder:: Master
.. tsc_stakeholder:: Peon
Within requirement declarations:

• Use the stakeholders option to identify the stakeholder(s) the requirement originated from.
• Use the exported_to option to export the requirement to a stakeholder.
.. tsc_req:: Collect wood

:id: REQ_COLLECT_WOOD
:stakeholder: Master
:exported_to: Peon
The tsc_stakeholder directive provides a lot of options to capture relevant information about the stakeholder,
in line with the concepts presented in [TSC-SPHINX-MANUAL-R1-RMP]). Refer to the directive reference
12.4 Allocation
Use the allocated_to option to allocate a requirement to a configuration item.
.. tsc_ci:: Sphinx

:allocated_to: Sphinx
Important: Requirements may be allocated to multiple configuration items. This is extremely useful to avoid
repeating identical requirements that apply to multiple configuration items.
Equivalently, you may use the tsc_allocate directive to allocate a requirement to a CI. Specify the require-
ment(s) to allocate using the requirements option, then specify the allocated CI with the ci option. Justifica-
tion for the allocation can be given using the justification option.
.. tsc_ci:: Sphinx

48 of 101 12.2. Traceability


.. tsc_allocate:: Allocation of georgiousness to Sphinx

:requirements: REQ_SPHINX_GORGIOUS
:ci: Sphinx
:justification: Make it so.
Besides configuration items, requirements may be allocated to functions and artifacts.

To allocate a requirement to a function, use the tsc_allocate directive with the function option.
.. tsc_function:: Generate beautiful documentation

:id: SPHINX.F1

.. tsc_allocate:: Allocation of georgiousness requirement to sphinx

function
:function: SPHINX.F1
:justification: So I decide.
Allocation to artifacts is done using the tsc_allocate directive too, with the artifact option. Use the
artifact_ref option to document a specific location in the artifact (e.g. chapter name).
.. tsc_artifact:: TSC Sphinx User Manual

.. tsc_allocate:: Allocation of georgiousness requirement to sphinx

user manual
:artifact: TSC Sphinx User Manual
:artifact_ref: All of it.
:justification: If the manual is not gorgious, then there is a
contradiction.
Note: You can allocate requirements simultaneously to CIs, functions and artifacts using a single
tsc_allocate directive.
12.5 Status
Requirements may have a status. The possible status are:

• Applicable
• Under evaluation
• Unsupported
To specify the status of a requirements, use the status option.
12.5. Status 49 of 101

12.6 Class
To specify a class, use the class option. Requirement classes are pre-defined. The possible values are:
• Functional
• Architecture
• Environmental
• Performance
• RAMS
• Standards
• Documentation
• Process
• Miscellaneous
12.7 Compliance level
It is possible to specify a compliance level for requirements. This is useful to provide a level of flexibility on the
implementation of the requirements.
The possible levels are P1, P2 or P3. A typical interpretation is:
• P1: Mandatory requirement
• P2: Negotiable requirement
• P3: Optional requirement
To specify a compliance level, use the compliance_level option.
12.8 Verification
To specify a verification method, use the verification option.

The possible methods are:
• Review: a review of the implementing design will be carried out;
• Test: a test will be carried out to verify that the requirement is fulfilled. In this case, the requirement should
be traced by a suitable test. Refer to Verification and Testing.
• Analysis: an analysis should be produced. In this case, the requirement should be allocated to a suitable
artifact documenting the analysis and its result;
• Model: the requirement shall be modeled, and the model subjected to a formal demonstration of correctness;
50 of 101 12.6. Class

12.9 Safety
To specify if a requirement is safety related or not, use the is_safety_related option. The possible values
are True or False.
12.10 Specifications
Once requirements are defined in various places of the documentation, it is often useful to collect and present the
requirements in a structured requirement specification.
Use the tsc_req_list directive to generate a table listing all the requirements allocated to a configuration
item.
.. tsc_req_list:: Sphinx requirement list

:ci: Sphinx
The directive automatically generates an Excel sheet listing the requirements and the value of their options. This
sheet can be downloaded from a ‘[Click Here to Download]’ hyperlink in HTML. In PDF, the Excel sheet is
embedded in the file, and can be downloaded by clicking on the paperclip icon next to the directive header.
ment.
Note: This is useful for very large lists to avoid creating a “phone book” of requirements.
Use the tsc_req_spec directive to generate a requirement specification for a configuration item.
.. tsc_req_spec:: Sphinx requirement spec

:ci: Sphinx
This powerful directive will generate sections where requirements are sorted and repeated:
• Functional requirements section, sorted by functions
• Non-functional requirements sections, sorted by class.
• Exported requirements section, sorted by stakeholders
• Unsupported requirements section
Important: The signature of an artifact using the tsc_req_spec or tsc_req_list directive will depend
on the generated content of both directive.
Therefore, if you modify a requirement in the documentation, the signature of all requirement specs listing the
requirement will be modified.
12.11 Traceability matrices
The tsc_req_traceability_matrix will generate a traceability matrix of requirements for a configura-

tion item.
The directive automatically generates an Excel version of the matrix. It can be downloaded from a ‘[Click Here
to Download]’ hyperlink in HTML. In PDF, the Excel sheet is embedded in the file, and can be downloaded by
clicking on the paperclip icon next to the directive header.
For example:
12.9. Safety 51 of 101

.. tsc_req_spec_traceability_matrix:: Sphinx RTM

:ci: Sphinx
:excel_only:
The matrix is split in two parts:

• The left part of the table (Source) shows the requirements of the configuration item to trace. For each
requirement, the CI and the status is provided.
• The right part of the table (Target) shows:
– The requirements that have the left requirement as source;
– The activities to which the left requirement was allocated;
– The stakeholders to which the left requirement was exported;
– The artifacts to which the left requirement was allocated;
Important: The signature of an artifact using this directive will depend on the generated content.
Therefore, if you modify a requirement, or a traceability of a requirement, the signature of all artifacts showing a
related traceability matrix will be modified.
It is usually recommended to specify the excel_only option to only generate the Excel sheet and not display
the matrix in the document.
52 of 101 12.11. Traceability matrices

CHAPTER
THIRTEEN
FUNCTIONS
Sphinx offer directives to document a functional analysis according to the ARCADIA methodology
[TSC-SPHINX-MANUAL-R3-ARCADIA].
Note: Relevant directives: tsc_function, tsc_mode, tsc_functional_variable, tsc_functional_traceability
13.1 Declaring functions
To declare functions, use the tsc_function directive. The function must be given a unique identifier using the
id option.
Use the definition option to document the function purpose in plain english. This text will be inserted in the
documentation when the function needs to be introduced (e.g. requirement specifications).
.. tsc_function:: Go to the moon

:ID: F.MOON
Functions can be decomposed in sub-functions. To declare a function as a sub-function of another one, use the
contained_in option.

:id: F.MOON
:definition: Putting a man on the moon
.. tsc_function:: Launch
:id: F.MOON.LAUNCH
:contained_in: F.MOON
:definition: Transport crew from ground to Earth orbit.
.. tsc_function:: Leave Earth orbit

:id: F.MOON.LEAVE_EARTH
:definition: Leave Earth orbit and travel to the moon.
.. tsc_function:: Enter Moon orbit

:id: F.MOON.ENTER_MOON
:definition: Enter a stable orbit around the moon.
.. tsc_function:: Land on the moon

:id: F.MOON.LAND_MOON
:definition: Land a crew on the moon
13. Functions 53 of 101

Note: Sphinx will automatically calculate the sub-functions list for each function. This will be reported in the in
the data box of the directive.
13.2 Allocation
Functions may be allocated to configuration items. Use the allocated_to option for that.
Functions may also be allocated to stakeholders. Use the stakeholders option for that.

:id: F.MOON
:stakeholders: NASA
.. tsc_function:: Launch
:id: F.MOON.LAUNCH
:allocated_to: SATURN 5 Rocket
.. tsc_function:: Leave Earth orbit

:id: F.MOON.LEAVE_EARTH
:allocated_to: Common and Service Module
.. tsc_function:: Enter Moon orbit

:id: F.MOON.ENTER_MOON
:allocated_to: Common and Service Module
.. tsc_function:: Land on the moon

:id: F.MOON.LAND_MOON
:allocated_to: Lunar Module
13.3 Inputs and outputs
Functions consume inputs and produce outputs. To declare inputs or outputs, use the
tsc_functional_variable directive.
.. tsc_functional_variable:: Coffee Bean
.. tsc_functional_variable:: Water
.. tsc_functional_variable:: Coffee
.. tsc_function:: Make coffee

:id: F.MAKECOFFE
:input: Coffee Bean, Water
:output: Coffee
54 of 101 13.2. Allocation

13.4 Associated interfaces
You may associate functional variables to interfaces. Interfaces are represented as configuration items (see Con-
figuration items)
To do so, use the associated_interface option.
.. tsc_functional_variable:: Coffee Bean

:associated_interface: Coffee tank
.. tsc_functional_variable:: Water
:associated_interface: Water tank
.. tsc_functional_variable:: Coffee
:associated_interface: Output tap

:id: F.MAKECOFFE
:input: Coffee Bean, Water
:output: Coffee
You may also associate interfaces to functions. Sphinx will automatically add the interfaces associated to variables
to the functions that use these variables.
Important: That way, it is not possible to forget an interface in the functional specification.
You may also specify interfaces that should be excluded from the list of associated interfaces. Use the
excluded_interface option to that effect.
Functional variables have multiple options. Refer to the directive reference for a complete list.
13.5 Realizing functions
You may specify a realization relationship between functions defined in different phases of the system design
process.
For instance, a function F1 defined at the conceptual design stage may be realized by a function FA defined at the
architectural design stage.
This would be modeled as follows:
Conceptual stage
================
.. tsc_function:: Do something crazy

:id: FBE_CRAZY

:id: F.MOON
:stakeholders: NASA
:realized_function: FBE_CRAZY
13.4. Associated interfaces 55 of 101

13.6 Safety
It is possible to assign a safety integrity level (SIL) to functions, To do so, use the sil option.
The possible values are:
• Undefined (the default value)
• Basic
• 1
• 2
• 3
• 4
• NA
13.7 Modes
It is possible to assign modes to a function. To do so, declare modes using the tsc_mode option, then assign
those modes to modes option of the relevant functions.
.. tsc_mode:: On
.. tsc_mode:: Off

:id: F.MAKECOFFE
:modes: On
13.8 Traceability matrix
The tsc_function_traceability_matrix will generate a traceability matrix of function realization.

Given the list of functions of a CI, it will report what functions are realizing these functions.
56 of 101 13.6. Safety

CHAPTER
FOURTEEN
RAMS
TSC Sphinx extension provides directives to support safety activities, in particular the definition and maintenance
of a hazard log.
Note: Relevant directives: tsc_req, tsc_cause, tsc_hazard, tsc_hazard_log
14.1 Declaring hazards, causes and mitigations
To define a hazard, use the tsc_hazard directive.
.. tsc_hazard:: Accidental contact of colleagues with hot liquids

:id: HAZ_OUCH
To define a cause that can lead to a hazard, use the tsc_cause directive.
.. tsc_cause:: the coffee machine fell down

:id: CAUSE_1
Use the cause option on a hazard declaration to link cause to hazard.
.. tsc_hazard:: Accidental contact of colleagues with hot liquids

:id: HAZ_OUCH
:cause: CAUSE_1
Mitigations are declared as regular requirements, using the tsc_req directive. However, use the
is_mitigation flag to identify the requirement as a mitigation.
.. tsc_req:: the coffee machine shall be installed on a stable table

:id: MITIG_1
:is_mitigation: True
To apply the mitigation to a cause, use the mitigation option on the cause.
.. tsc_cause:: the coffee machine fell down

:id: CAUSE_1
:mitigation: MITIG_1
14. RAMS 57 of 101

14.2 Hazard log
Use the tsc_hazard_log directive to generate the hazard log table.
.. tsc_hazard_log:: Coffee machine Hazard log

:as_paragraph:
The hazard log is presented in 4 parts (subsets of columns):

• the hazards,
• the causes,
• the mitigations,
• the requirements tracing mitigation.
The tsc_hazard_log directive provides options for selecting the contents of the hazard log. Refer to the
directive reference
58 of 101 14.2. Hazard log

CHAPTER
FIFTEEN
ROLES AND ACTIVITIES
TSC Sphinx extension provides support for defining roles and activities in plans, and produce the corresponding
RACI matrix.
Note: Relevant directives: tsc_role, tsc_activity, tsc_raci
15.1 RACI
Use the tsc_activity directive to document an activity.
.. tsc_activity:: Make coffee
Prepare coffee on request of the customer.
In order to assign responsibility for an activity, it is necessary to define organizational roles first. Use the
tsc_role directive for that.
.. tsc_role:: Bartender
Prepares the coffee.
.. tsc_role:: Customer
Orders the coffee.
.. tsc_role:: Bar owner
Owns the place.
.. tsc_role:: Waiter
Serves the coffee when ready.
Then, assign the roles to the activity. There are four possible options, according to the RACI methodology:
• responsible_roles - Role(s) in charge of doing the activity;
• accountable_role - Role ultimately accountable for the activity. There can only be one;
• consulted_roles - Role(s) consulted when doing the activity;
• informed_roles - Role(s) informed of the outcome of the activity;
This is an example.
15. Roles and activities 59 of 101


:responsible_roles: Bartender
:accountable_role: Bar owner
:consulted_roles: Customer
:informed_roles: Waiter
Use the tsc_raci directive to recapitulate all the responsibilities assigned for the activities defined in the en-
closing document.
.. tsc_raci:: Responsibility assignment matrix

:as_paragraph:
Note: It is customary to add the as_paragraph option for an optimal presentation.
15.2 Inputs and products
Activities consume and produce artifacts. Use the input and product options to define them. For instance:
.. tsc_artifact:: Coffee beans

:generic: True
.. tsc_artifact:: Cup
:generic: True
.. tsc_artifact:: Water
:generic: True
.. tsc_artifact:: Cup of coffee

:generic: True

:input: Coffee beans, Cup, Water
:product: Cup of coffee
Furthermore, it is possible to document entry and exit criteria, that is, conditions that must be fulfilled to start
or complete the activity. Such matters are to be entered as a text paragraph using the entry_criteria and
exit_criteria options. Extending on our example:

:entry_criteria: Sufficient coffee beans are available. A clean
cup is available. Water tank is not empty.
:exit_criteria: Coffee is available
15.3 Tools
Activities may require tools. In this case, use the tools option to reference the appropriate configuration item:
.. tsc_ci:: Coffee machine

:tools: Coffee machine
60 of 101 15.2. Inputs and products

15.4 Phase
It is possible to document the CENELEC phase at which an activity belongs. Use the phase option for that
purpose. The list of possible phases is restricted. Refer to the directive reference tsc_activity.
This is example:

:phase: 0 - Planning
15.5 Requirements
It is possible to specify requirements that are applicable to an activity. Use the requirements option for that
and refer to Requirements to use this feature for requirement tracing purposes.
15.4. Phase 61 of 101

CHAPTER
SIXTEEN
SOFTWARE & TOOLS
Directives are provided to support software documentation.
Note: Relevant directives: tsc_coding_rules, tsc_tool_class, tsc_tool_list, tsc_sw_standard_conformity
Note: This section will be detailed in a subsequent release of the manual.
62 of 101 16. Software & Tools

CHAPTER
SEVENTEEN
VERIFICATION AND TESTING
Note: Relevant directives: tsc_test_case, tsc_test_scenario, tsc_test_scenario_result, tsc_static_verification,

tsc_static_verification_result, tsc_verification_traceability_matrix, tsc_interface_traceability_matrix
Note: Obsolete directives: tsc_test_case_result
17.1 Declaring test cases
A test case should be declared in the test specification artifact. To declare test cases, use the tsc_test_case
directive. The test case must be given an unique name.
.. tsc_test_case:: Unique Name
Use the requirements or interface option to document the test case traceability to requirements or inter-
faces.
.. tsc_test_case:: Unique Name1
:requirements: req_1, req_2

:requirements: interface_1, interface_2
Use the family option to document the test case type (functional, dis-functional, integration . . . )
:family: Functional
Use the parameters option to document the test case parameters

:family: Functional
:parameter: parameterX = 1, parameterY = 5
Use the pre-condition option to document the test case pre-condition.

:family: Functional
:pre-condition: The Device under test should start since 5 minutes
Use the required_configuration option to document the test case Device under test (DUT) configuration.
17. Verification and Testing 63 of 101


:family: Functional
:required_configuration: A complet computer box link to a CPM
Use the action option to document the test case action to be performed when the test_case is import from
another tool. This option should take only artifact as input.

:family: Functional
:action: Vector-Cast profil
17.2 Declaring test scenarios
A test scenario should be declared in the test specification artifact. To declare test scenarios, use the
tsc_test_scenario directive. The test scenario must be given an unique name.
.. tsc_test_scenario:: Unique Name
You may use the source option to document a source code file that implements the test scenario. The system
will compute automatically a signature on this source code that will be rendered in the verification traceability
matrix.
Use the family option to document the test case type (functional, dis-functional, integration . . . )

:family: Functional
Use the test_cases option to document the test scenario traceability to test cases.

:family: Functional
:test_cases: TC_1, TC_2
Use the parameters option to document the test scenario parameters

:family: Functional
:parameters: parameterX = 1, parameterY = 5
Use the pre-condition option to document the test scenario pre-condition.

:family: Functional
Use the required_configuration option to document the test scenario Device under test (DUT) configu-
ration.
64 of 101 17.2. Declaring test scenarios


:family: Functional
Use the action option to document the test scenario action to be performed when the test_case is import from
another tool. This option should take only artifact as input.

:family: Functional
:action: Vector-Cast profil
17.3 Auto documenting python test scenario
It is possible to create a test scenario from a python function.

For example, suppose there exists python module test_parrot with a function test_hi. In order to declare
this function as a test scenario, use the autotsc_test_scenario directive, and provide as an argument the
python function name, as accessible in the python path.
.. autotsc_test_scenario:: test_parrot.test_hi
Sphinx will automatically document the source and source_signature option of the test scenario by using
the python source file.
In the documentation string of the function, you may document the options as if you were entering the test scenario
in Sphinx. In the example above, this is a possible documentation of the test_hi function.
def test_hi():
"""
:requirements: REQ_HI
This test scenario verifies that the parrot can says hi.
"""
assert parrot.say("hi") == "hi"
17.4 Declaring static verifications
A static verification should be declared in the test specification artifact. To declare static verifications, use the
tsc_static_verification directive. The static verification must be given an unique name.
.. tsc_static_verification:: Unique Name
Use the requirements or interface option to document the static verification traceability to requirements
or interfaces.
.. tsc_static_verification:: Unique Name1


:requirements: interface_1, interface_2
17.3. Auto documenting python test scenario 65 of 101

Use the type option to document the type of static verification (Code reading, Computation etc.).

:type: artifact review
Use the artifact option if the static verification is on the artifact. In this option only previously declare artifact
should be used.
.. tsc_static_verification:: Check the presence of the traceability matrix

:requirements: req_1
:type: artifact review
:artifact: Supplier requirement specification
Use the ci option if the static verification is on the configuration item. In this option only previously declare
configuration item should be used.
.. tsc_static_verification:: Check the color of the box

:requirements: req_1
:type: visual verification
:ci: Box
17.5 Declaring test scenario results
A test scenario result should be declared in the test report artifact. To declare test scenario results, use
the tsc_test_scenario_result directive. The test scenario result must be given test scenario using
test_scenario option.
.. tsc_test_scenario_result::
:test_scenario: TS_1
Use the who option to document who perform the test scenario.
:who: John Doe
Use the result option to document who perform the test scenario. The possible results are:
• OK all the check inside the test scenario are verified
• KO some check inside the test scenario are not verified
• JOK (justified OK) Some check inside the test scenario are not verified however the reason for this can be
justified.
:who: John Doe
:result: ``JOK``
In case of result to JOK a justification is needed. To do that the option justification is used.
:who: John Doe
:result: ``JOK``
:justification: The TS_1 is wrong only at the init this don't
have any impact on the global performance
Use the issue option to document the issue create following the execution of this test scenario.
66 of 101 17.5. Declaring test scenario results

:who: John Doe
:result: ``NOK``
:issue: #1250, #1800
17.6 Declaring static verification results
A static verification result should be declared in the test report artifact. To declare static verification results, use
the tsc_test_scenario_result directive. The static verification result must be given static verification
using test_scenario option.
.. tsc_static_verification_result::
:verification: SV_1
Use the who option to document who perform the static verification.
:verification: SV_1
:who: John Doe
Use the result option to document who perform the static verification. The possible results are:
• OK all the check inside the static verification are verified
• KO some check inside the static verification are not verified
• JOK (justified OK) Some check inside the static verification are not verified however the reason for this can
be justified.
:verification: SV_1
:who: John Doe
:result: ``JOK``
In case of result to JOK a justification is needed. To do that the option justification is used.
:verification: SV_1
:who: John Doe
:result: ``JOK``
:justification: The TS_1 is wrong only at the init this don't
have any impact on the global performance
Use the issue option to document the issue create following the execution of this static verification.
:verification: SV_1
:who: John Doe
:result: ``NOK``
:issue: #1250, #1800
17.6. Declaring static verification results 67 of 101

17.7 Declaring verification traceability matrix
A verification traceability matrix should be declared in the test specification artifact. To declare verification trace-
ability matrix, use the tsc_verification_traceability_matrix directive. The verification traceabil-
ity matrix must be given an title and the ci on for which you want the traceability matrix.
.. tsc_verification_traceability_matrix:: Title
:ci: Component_1
Use the filter-Function option to filter some part of the traceability matrix. This option is parameter with
a piece of python code that will return True or False based the data of an instance.
For example to trace only the requirement beginning by EN50128 you can used:
:ci: Component_1
:filter_function: r["code"].startswith("EN50128")
Use the excel_only if you want to generate only an excel file that will be integrated in the document but not
the traceability matrix in the document itself. The possible parameter are:
• True to have only a excel file include in the document
• False to have an excel file include in the document and a table representing the traceability matrix
:ci: Component_1
:excel_only: True
Use the page_layout option to decide the layout of the table representing the traceability matrix. This option
is ignore if the option excel_only is at “True” The possible parameter are:
• A4 to keep it in A4
• A3_Landscape to put in in an A3 in landscape
:ci: Component_1
:excel_only: False
:page_layout: a3_landscape
Use the justification option to add in the justification column of the traceability matrix
a justification. This option have the following format: RequirementId1#Justification1,
RequirementId2#Justification2 with the RequirementId the Id of a requirement of the trace-
ability matrix and the Justification is in plain english
:ci: Component_1
:excel_only: False
:justification: ReqId1:Justif1,ReqId2:Justif2,ReqId3,Justif3
68 of 101 17.7. Declaring verification traceability matrix

17.8 Declaring interface traceability matrix
A interface traceability matrix should be declared in the test specification artifact. To declare interface traceability
matrix, use the tsc_interface_traceability_matrix directive. The interface traceability matrix must
be given an title.
.. tsc_interface_traceability_matrix:: Title
Use the filter-Function option to filter some part of the traceability matrix. This option is parameter with
a piece of python code that will return True or False based the data of an instance.
For example to trace only the interface beginning by IEVC.IF you can used:
:filter_function: v["code"].startswith("IEVC.IF")
Use the excel_only if you want to generate only an excel file that will be integrated in the document but not
the traceability matrix in the document itself. The possible parameter are:
• True to have only a excel file include in the document
• False to have an excel file include in the document and a table representing the traceability matrix
:excel_only: True
Use the page_layout option to decide the layout of the table representing the traceability matrix. This option
is ignore if the option excel_only is at “True” The possible parameter are:
• A4 to keep it in A4
• A3_Landscape to put in in an A3 in landscape
:excel_only: False
Use the justification option to add in the justification column of the traceability matrix
a justification. This option have the following format: RequirementId1#Justification1,
RequirementId2#Justification2 with the RequirementId the Id of a requirement of the trace-
ability matrix and the Justification is in plain english
:excel_only: False
:justification: ReqId1:Justif1,ReqId2:Justif2,ReqId3,Justif3
17.8. Declaring interface traceability matrix 69 of 101

CHAPTER
EIGHTEEN
QUALITY ASSURANCE
Note: Relevant directives: tsc_qa_report
Use the tsc_qa_report directive to create a quality report on the generated documentation. This report anal-
yses the sphinx declaration and reports errors, warnings and information in a spreadsheet.
.. tsc_qa_report::
This is a beautiful QA report. Enjoy.
The directive takes no argument nor has any special option.

The checks verify requirements from [TSC-SPHINX-MANUAL-R1-RMP] and
[TSC-SPHINX-MANUAL-R2-CMP], as well as additional RAMS requirements recorded in
[TSC-SPHINX-MANUAL-R3-SPHINXRS].
These are examples of some of the checks carried out:
• Requirements should have a stakeholder or a source;
• Non top-level configuration items should not be orphans;
• Hazards should have a cause;
• Etc.
70 of 101 18. Quality Assurance

CHAPTER
NINETEEN
UTILITIES
Note: Relevant directives: tsc_xlsx_data, tsc_recap_table
19.1 Recap tables
Use the tsc_recap_table directive to create a table listing the instances of a given directive.
Note: This can be seen as a query on the database of the declared TSC directives.
Warning: This directive is powerful but a bit technical. You are warned.
The directive to query should be specified using the directive_name option. Then:
• The header_fields option specifies the options of the directive that should be shown in the table, as a
python string list. To display the argument of the directive, use the name “argument”;
• The colwidths option should specify the relative width of the columns;
• The sort_key option specifies the option to use as the sorting key for the rows in the table;
It is possible to specify a python filter function. This function will take as an input a variable ‘v’ that will contain
a python dictionary of the option values of each declared directive.
The filter_function option should be a boolean expression that returns true for those directive that need to
be retained in the table.
This is a practical example:
.. tsc_role:: Ninja
.. tsc_role:: Chief Ninja
.. tsc_role:: Samurai
.. tsc_recap_table:: All roles with Ninja in the title

:directive_name: tsc_role
:header_fields: ["argument"]
:colwidths: [1]
:sort_key: argument
:filter_function: "Ninja" in v["argument"]
:as_section:
This table will list all declared roles that contain the word
"Ninja" in their argument.
19. Utilities 71 of 101

Warning: Recap tables do not influence the signature of the document. So beware that if you change
something that impacts a recap table, it will not necessarily update the document signatures.
19.2 Importing directives from Excel
Use the tsc_excel_data directive.

This meta-directive reads lines from an Excel sheet as if they were individual directive declarations, where the
value of each option are given in a column.
Use the directive_name option to specify the name of the directive, and the file option to specify the path
to the Excel file to read.
• The first line must contains the name of the TSC option corresponding to the column. The reader will ignore
columns after the first column with an empty cell on the first line.
• The last line must contain the special value TSC_EXCEL_EOF. If this line does not exist, then the reader
will attempt to read all the lines up to the value specified in the max_row option. When this happens, the
builder will fail to prevent data from being lost. The default value of max_row is 10000.
• There must be one column with the name ‘is_ignored’. This column can be used to instruct the Excel reader
to skip a line. Enter ‘Yes’ for the line to be ignored. By default, the line is not ignored.
This is an example to import maximum 1000 requirements defined in a data.xlsx file.
.. tsc_xlsx_data:: Requirement import

:directive_name: tsc_req
:file: data.xlsx
:max_row: 1000
19.3 Importing directives from CSV files
Use the tsc_excel_data directive, specifying the path to the CSV file in the file option.
72 of 101 19.2. Importing directives from Excel

CHAPTER
TWENTY
BUILDING DOCUMENTATION
In general, building documentation using sphinx is done using a specific sphinx-build command available in
the Python scripts directory. Call it from the directory where your conf.py file is located like this:
sphinx-build -b html . _build/doc/html
The -b switch allows to select the builder by its name (here html).
The second argument is the source path (where the conf.py is located). The third is the destination directory of
the documentation built.
You may tweak builder behavior using configuration variables in the conf.py file.
Each builder may have specific options. You may refer to the Sphinx builder documentation <https://www.sphinx-
doc.org/en/master/usage/builders/index.html> for a detailed description.
20.1 html
This builder produces HTML documentation. There is nothing much more to say about it.
20.2 tsc_json
TSC added a JSON builder. This builder will extract all directives data and dump it in a series of json files, each
file being named by the directive name (e.g. tsc_req.json). These files can be imported as data sources in
Excel for analysis or quality check purposes.
class tsc_sphinx.builder.TSCJSONBuilder(
app: Sphinx)
This builder exports all the directives found in the documentation as JSON objects. The builder name is
tscjson.
For each directive, a .json file is created, named after the directive (e.g. .. tsc_req:: directives
will be written to tsc_req.json).
The JSON content is a list of objects. Each object has the following standard fields:
Parameters
• docname – the name of the document where the directive is located
• lineno – the line number in the document where the directive is located
• element_id – the unique identifier for this directive declaration.
• tsc_title_string – the string to use when rendering the directive as a section
• tsc_ref_string – the string to use when displaying a link to the directive definition
from somewhere else in the documentation
20. Building documentation 73 of 101

In addition, each object also receives the value of the directive-specific options used in the directive decla-
ration.
The following values can be configured in your conf.py.
tsc_builder_filter
List of document names to exclude from the TSC builders. This option is useful when you want to restrict
the JSON dumps to a specific subset of the documentation. It is an empty list by default.
Note: This is used by TSC master build to remove test directives from the JSON production build.
20.3 latex
The latex builder produces latex files in the build directory, with a make file to call the PDF generator. The
general Sphinx design is that the list of PDF files to generate should be specified in a latex_documents
configuration variable.
Note: For the iEVC documentation, an automatic selection of artifact is coded in the conf.py.
The latex_documents variable is automatically filled with the artifacts that are in Review or Published status.
The only gotcha is that it is necessary to generate first the documentation in JSON to know about these artifacts
before running the latex build.
Therefore, when generating the iEVC documentation, you should run the JSON build before calling the latex
build. If you don’t, no latex code will be generated.
Note: For windows users, the make_pdf.bat script will do all that stuff for you.
tsc_latex_variables
A dictionary mapping a latex document name to a dictionary of variables. Each entry in this dictionary is a
value that will be passed to the Sphinx latex template
For example:
tsc_latex_variables["galactic/guide"] = {"meaningofuniverse": 42}
Will pass 42 in a variable meaningofuniverse to the latex template of the latex document galactic/
guide.
This variable can be retrieved in the Sphinx latex.tex_t template using the following syntax:
<%= meaningofuniverse %>
There is an annoying feature of Sphinx that, in latex and PDF, moves the reference documents out of where they
are declared to the end of the document. This behavior is not what TSC wanted, so TSC wrote a patch (called a
transform) that can be used to cancel it.
To do this, add the following lines to your conf.py:
import sphinx.builders.latex.transforms
from tsc_sphinx.builder import TSCBibliographyTransform
sphinx.builders.latex.transforms.BibliographyTransform = TSCBibliographyTransform
74 of 101 20.3. latex

20.4 spelling
This is a spell checker builder that produces a spelling report. Refer to Spell checking.
20.4. spelling 75 of 101

CHAPTER
TWENTYONE
SPELL CHECKING
Spelling check is done through a special builder called spelling. This builder produces a single result file
_build/doc/spelling/output.txt.
The related CMake target is tsc_doc_spelling, or under Windows:
.\make_spelling.bat
Each line in this file indicates a word that is believed to be not spelled correctly. There are two possible situations.
1. Either the word is indeed not spelled correctly. Just fix it.
2. The word is an acronym or a legit name that the dictionary used by the spelling checker does not know.
In the latter case, there are various ways to remedy the problem.
You may create a spelling_wordlist.txt file in the same directory as your conf.py. Each line of this
file documents an additional word that the spelling checker should accept. Add the word at the end of this file and
run the checker again.
It is also possible to add acceptable words in the document itself. Use the spelling directive, as follows:
.. spelling::
BizarreWord
Otherbizarreword
Finally, if there are entire sections of your document that are not to be inspected for spelling purposes, you can
use the only directive and the not modifier to have it skipped by the Sphinx spelling builder.
.. only:: not spelling
This wil naut be spel checkked (thankfully)
76 of 101 21. Spell checking

CHAPTER
TWENTYTWO
EXPERIMENTAL FEATURES
Warning: Use at your own risk.
22.1 Bill of quantity
To display a BOQ, use the tsc_boq directive, specifying the top-level CI using the ci option.
22. Experimental features 77 of 101

CHAPTER
TWENTYTHREE
DIRECTIVES REFERENCE
This documentation enumerates all TSC Sphinx directives and details the meaning of all the available options.
23.1 tsc_activity
class tsc_sphinx.tsc_sphinx.tsc_activity
Parameters
• input – A comma separated list of tsc_artifact IDs.
• product – A comma separated list of tsc_artifact IDs.
• entry_criteria – What must be true for this activity to start.
• exit_criteria – What must be true for this activity to be considered complete.
• responsible_roles – role of the person who do the work to complete the activity
• accountable_role – role of the people that is ultimately answerable for the correct
and thorough completion of the activity,the one who ensures the prerequisites of the task
are met and who delegates the work to those responsible
• consulted_roles – role of persons whose opinions are sought
• informed_roles – role of persons, who are kept up-to-date on progress
• requirements – Requirements applicable to this activity.
• tools – Tools relevant for this activity.
• phase – Assign a V cycle phase to the activity. This is used to group related activities
in V cycle representations phase can be one of the following: 0 - Planning, 1 - Concept,
2 - System Definition & Operational Context, 3 - Risk Analysis And Evaluation, 4 -
Specification Of System Requirements, 5 - Architecture & Apportionment Of System,
6 - Design & Implementation, 7 - Manufacture, Safety, Feasibility
23.2 tsc_artifact
class tsc_sphinx.tsc_sphinx.tsc_artifact
This directive declares an artifact.
Parameters
• type – The type of artifact. Artifact type cannot be CI, and can be one of the following:
Doc, Software, Model, Excel, Software Package
• source – Source of the artifact, from which the artifact version signature is calculated.
• signature – Artifact signature. This is calculated and should not be set manually. If
set, it will be ignored.
78 of 101 23. Directives reference

• current_version_name – Current artifact version name. This should only be set

if the argument has no source.
• current_version_date – Current artifact version date. This should only be set if
the argument has no source.
• current_version_author – Current artifact version author. This should only be
set if the argument has no source.
• current_version_authorizer – Current artifact version authorizer. This
should only be set if the argument has no source.
• current_version_mr – Merge request documenting the review of current ver-
sion.This should only be set if the argument has no source.
• current_version – Pointer to the current version data of the artifact. This is cal-
culated and should not be set manually. If set, it will be ignored.
• higher_version_name – Higher documented version name. This is calculated and
should not be set manually. If set it will be ignored. Default value is V0.
• higher_version_author – Higher documented version author. This is calculated
and should not be set manually. If set it will be ignored. Default value is TBD.
• higher_version_authorizer – Higher documented version author. This is cal-
culated and should not be set manually. If set it will be ignored. Default value is TBD.
• force_unversioned – Set this to True in case the artifact should always have a
version name set to UNVERSIONED. Boolean values must be ‘True’ or ‘False’ Default
value is False.
• sphinx_docname – If this artifact is a doc built by Sphinx, this is the docname, that
is, the name of the doc in the TOC tree.
• sphinx_latex_show_secnum – If this artifact is a doc build by Sphinx, set this
flag to NOT include automatic section numbers in the Latex / PDF output. Boolean
values must be ‘True’ or ‘False’ Default value is True.
• status – This parameter is changed by tsc_artifact_status directive. It should not be
set manually. If set, it will be ignored. Default value is Planned.
• base_url – When the artifact is located outside of TSC, it is possible to specify the
base URL, that is the external website URL where the artifact is located.
• file_name – The artifact file name. When the artifact is build by Sphinx, it is calcu-
lated automatically.
• file_id – The document ID. When the artifact is build by Sphinx, it is calculated
automatically.
• mime_type – The MIME type guessed from the file extension. Most of the time, it is
better to let Sphinx guess it from the file extension.
• generic – Some artifacts are just abstract names to represent a class of concrete arti-
facts (e.g. ‘Specifications’, ‘Manuals’, etc). Such artifact should set this flag to True. It
is False by default. Boolean values must be ‘True’ or ‘False’ Default value is False.
• instance_of – Indicates that this artifact is a concrete instance of a generic artifact.
• path – Access path on the server. When the artifact is built by Sphinx, this attribute is
computed.
• lib_url – URL of the artifact in the library, if any. When the artifact is built by
Sphinx or has a source, it is calculated automatically.
• html_url – URL of the artifact in the TSC HTML documentation, if any. When the
artifact is built by Sphinx, it is calculated automatically.
• builddir – Where the artifact is built. This is calculated for artifacts built by Sphinx.
23.2. tsc_artifact 79 of 101

• phase – CENELEC Phase were the artifact produced phase can be one of the follow-
ing: 0 - Planning, 1 - Concept, 2 - System Definition & Operational Context, 3 - Risk
Analysis And Evaluation, 4 - Specification Of System Requirements, 5 - Architecture
& Apportionment Of System, 6 - Design & Implementation, 7 - Manufacture, Safety,
Feasibility
• isa_ranking – Ranking of the artifact for an ISA. ISA ranking can be one of the
following: Primary, Secondary Default value is Secondary.
• requirements – Requirements applicable to this artifact.
23.3 tsc_artifact_history
class tsc_sphinx.tsc_sphinx.tsc_artifact_history
This directive represents an artifact history.
Parameters artifact – The artifact which history is to be recapped
23.4 tsc_artifact_status
class tsc_sphinx.tsc_sphinx.tsc_artifact_status
This directive documents a status of an artifact.
Parameters
• artifact – Artifact whose status will be changed.
• status – Status of the artifact. Artifacts are initially planned, then reviewed, then
published. This flag is used by TSC CI/CD to know if the artifact must be deployed to
the artifact library, copied in the review area, or left alone. Artifact status can be one of
the following: Planned, Review, Published, Obsolete Default value is Planned.
23.5 tsc_artifact_list
class tsc_sphinx.tsc_sphinx.tsc_artifact_list
This directive inserts an artifact list in the document. The list display the phase, version and status of each
artifact.
Parameters
• ci – CI for which to generate an artifact_list.
• filter_function – A piece of python code that will return True or False based the
data of an instance. The instance data is provided as a dictionary variable v.
• page_layout – Select a page layout for the rendering of the table Page layout can be
one of the following: A4,A3_Landscape Default value is a3_landscape.
• excel_only – Don’t show the full table in the doc. Only provide Excel file. Boolean
values must be ‘True’ or ‘False’ Default value is False.
• recursive – If this option is set to true, the list will include all the child CIs of the
specified CIs. Boolean values must be ‘True’ or ‘False’ Default value is False.
80 of 101 23.3. tsc_artifact_history

23.6 tsc_artifact_version
class tsc_sphinx.tsc_sphinx.tsc_artifact_version
This directive documents a version of an artifact.
Parameters
• artifact – Artifact being versioned.
• name – Name of the version (it can be any string)
• date – Date of the version Correct date format is DD/MM/YYYY
• signature – Signature of the version. It is a SHA-1 hash of the concatenated source
files.
• author – Author of the document
• authorizer – Authorizer of the document
• description – Description.
• mr – Associated Merge Request (e.g. !123)
• path – Optional argument to specify a path for the version of an external artifact.
• file_name – Optional argument to specify a filename for the version of an external
artifact.
23.7 tsc_assumption
class tsc_sphinx.tsc_sphinx.tsc_assumption
Documents a assumption on a baseline.
Parameters
• id – Unique identifier of the assumption
• ci – The CI being targeted by the assumption
• source – The artifact where the assumption originates from.
• is_safety_related – Assumption is safety related. Safety related status can be
one of the following: Undefined, Yes, No. Default value is Undefined.
• is_cybersecurity_related – Assumption is cybersecurity related. Cybersecu-
rity related status can be one of the following: Undefined, Yes, No. Default value is
Undefined.
• status – documents the safety status of the assumption. Assumption status can be
one of the following: open, closed, exported. Default value is Open.
• status_justification – A text providing a justification for closing the assump-
tion.
• mitigations – Mitigation requirement to which the assumption is transferred.
23.6. tsc_artifact_version 81 of 101

23.8 tsc_attach
class tsc_sphinx.tsc_sphinx.tsc_attach
This meta-directive include a file as an attachment to a sphinx document
Parameters file – Path to the file to include.
23.9 tsc_allocate
class tsc_sphinx.tsc_sphinx.tsc_allocate
This directive allocates a requirement to a CI or an artifact.
Parameters
• requirement – The requirement to allocate
• ci – The CI on which requirements are allocated
• function – The function on which requirements are allocated
• artifact – The artifacts on which requirements are allocated
• artifact_ref – An optional reference to a specific location in the artifact (e.g. chap-
ter name)
• justification – The justification of this allocation
23.10 tsc_baseline
class tsc_sphinx.tsc_sphinx.tsc_baseline
Documents a baseline, that is, a frozen version of a configuration item. For each baseline, a signature is
calculated by compounding the signature of the artifacts of the CI and those of the sub-CIs.
A baseline is frozen when the baseline_signature option is documented with the signature of the version we
want to freeze. A human-friendly name can be documented.
If for any reason, the calculated signature deviates from the one documented, then the documented baseline
has been compromised and an error is generated.
Parameters
• ci – The CI(s) being baselined
• signature – The signature of the baseline. If the calculated signature does not match,
an error will be generated.
• name – The name of the current baseline.
• current_signature – Baseline calculated signature. This is calculated and should
not be set manually. If set, it will be ignored.
82 of 101 23.8. tsc_attach

23.11 tsc_cause
class tsc_sphinx.tsc_sphinx.tsc_cause
This directive declares a cause
Parameters
• id – Unique identifier of the cause
• mitigation – Mitigation(s) for this cause
• applicable – Specifies whether the cause is applicable Boolean values must be
‘True’ or ‘False’ Default value is True.
• justification – Justifies the applicability (or not) of the cause
• source – The artifact where the source originates from.
23.12 tsc_ci
class tsc_sphinx.tsc_sphinx.tsc_ci
This directive declares a configuration item.
A term:CI is an element of the product that can be manufactured or supplied. CIs can be composed of other
CIs in order to form a bill of material.
Parameters
• code – A code for the CI. Default value is None.
• type – The type of CI. CI can have one of the following types: COTS, Generic Com-
ponent, Project, Reused. Default value is Project.
• physical_type – The physical type of CI. CI can have one the following physical
type: Hardware, Software, Interface, Data. Default value is Hardware.
• sil – The maximum SIL (or SSIL for a software) assigned to a function assigned to
this CI. SIL can have one the following value: Undefined, Basic, 1, 2, 3, 4, Na. Default
value is Undefined.
• tool_classification – When CI is a tool, the tools classification shall be de-
scribed with a directive tsc_tool_class. If such directive exists this field is filled auto-
matically. Default value is None.
• status – The status of the CI. CI can have one the following status: New, Unmodified,
Modified. Default value is New.
• part_number – The part number of the CI. For a COTS, this is provided by the
supplier of the CI.
• artifacts – Hold the list of artifacts regrouped by the CI.
• supplier – List of supplier reference for the CI. (list of supplier ID)
• purchased_by – List of entity in charge of purchasing of the item. (list of supplier
ID)
• composed_of – Hold the assembly of CI
• quantity – number of CI (used for the bill of quantity) Default value is 1.
• safety_process – A string. CI can have one the following safety processes:
Generic Product, Generic Application, Specific Application, Undefined. Default value
is Undefined.
• top_level – Declares if the CI is a top-level one or not. Boolean values must be
‘True’ or ‘False’ Default value is False.
23.11. tsc_cause 83 of 101

23.13 tsc_ci_component
class tsc_sphinx.tsc_sphinx.tsc_ci_component
This directive adds components to a configuration item.
Parameters
• ci – The CI on which components should be added
• component – The components to add
23.14 tsc_ci_artifact
class tsc_sphinx.tsc_sphinx.tsc_ci_artifact
This directive adds artifacts to a configuration item.
Parameters
• ci – The CI on which artifacts should be added
• artifact – The artifacts to add
23.15 tsc_coding_rules
class tsc_sphinx.tsc_sphinx.tsc_coding_rule
This directive declares a coding rule. This directive allows to describe for a rule requirement of the standard
and application on the project.
Parameters
• standard – The name of the coding standard
• index – Index of rule in standard
• guideline – Identifier of the rule or the directive
• rule_category – Category of rule for the coding standard
• revised_category – Category of rule considered for the project
• justification – Category of rule considered for the project
• compiler_check – Check that can be done by the compiler
• code_checker – Check that can be done by the code checker
• manual_review – Manual Additional review to preform
23.16 tsc_function
class tsc_sphinx.tsc_sphinx.tsc_function
This directive identifies a function in the system.
Parameters
• id – Unique function ID. The ID given must be unique among all functions that will
be analyzed during documentation generation. Generation will fail in case it is not the
case.
• definition – Defines the function in plain english. This text will be inserted in the
documentation when the function needs to be introduced (e.g. requirement specifica-
tions).
84 of 101 23.13. tsc_ci_component

• allocated_to – Comma-separated list of CIs this function is allocated to.

• modes – Comma separated-list of modes this function is active in.
• stakeholders – Comma separated-list of Stakeholders this function is allocated to.
• contained_in – Comma-separated list of functions this function is contained in.
• realized_function – Comma-separated list of higher phase functions this func-
tion realizes.
• input – Comma-separated list of input variables to this function.
• output – Comma-separated list of input variables to this function.
• applicable – Defines if the function is applicable in the current baseline Boolean
values must be ‘True’ or ‘False’ Default value is True.
• sil – The highest safety level assigned to this function or one of its sub-functions. NA
means that such level is not applicable for the considered function SIL can have one the
following value: Undefined, Basic, 1, 2, 3, 4, Na. Default value is Undefined.
• associated_interface – The interfaces associated to this function
• excluded_interface – The interfaces to ignore in associated_interface list
• sub_functions – List of the sub functions of this function. Calculated and should
23.17 tsc_functional_variable
class tsc_sphinx.tsc_sphinx.tsc_functional_variable
This directive identifies a functional variable in the system.
Parameters
• objective – the goal of this variable (i.e. data, trigger an action . . . ).
• description – description of this variable (i.e. explain what it represents)
• family – Hardware or Software. Family values must be ‘Hardware’ or ‘Software’
Default value is Software.
• type – the type of the variable
• format – Format of the variable (i.e.
• unit – the unit of the variable
• precision – the precision of the variable
• protocol – the communication protocol of the variable
• equivalence_class – the equivalence classes of the variable
• forbidden_data – the forbidden value of the variable
• minimum – the minimum value of the variable
• maximum – the maximum value of the variable
• behavior_outside_range – How the variable act if a value is outside of its range
• memory_management – Where this variable is recorded.
• timing_constraints – What timing constraints are on this variable
• sil – What SIL is on this variable
• associated_interface – The interfaces associated to this functional variable
23.17. tsc_functional_variable 85 of 101

• produced_by – List of functions that produce this variable. Calculated and should
• consumed_by – List of functions that consume this variable. Calculated and should
• contained_in – Parent functional variable. For description of structured data
• write_access – Component that has write access for the variable
• read_access – Component(s) that has(have) read access for the variable
23.18 tsc_functional_traceability
class tsc_sphinx.tsc_sphinx.tsc_function_traceability_matrix
Create a traceability matrix that associate functions of a list configuration item to function pointed by the
field realize_function
Parameters
• ci – Comma-separated list of CIs for which to generate a traceability matrix.
• use_small_font – Use small font in pdf table, to be used for table with long func-
tion identifier Boolean values must be ‘True’ or ‘False’
• traceability_direction – Select the traceability direction top_down lists the
ci functions with the function realizing them, if any bottom-up lists the ci functions with
the function realized by them, if any Function traceability direction can be one of the
following: Bottom_Up,Top_Down Default value is bottom_up.
23.19 tsc_hazard
class tsc_sphinx.tsc_sphinx.tsc_hazard
This directive declares a cause
Parameters
• id – Unique identifier of the hazard
• status – Status of the hazard Hazard status allowed values: Open, Closed, Not Ap-
plicable. Default value is Open.
• justification_if_not_applicable – Justifies the not applicability of the
Hazard
• cause – The cause(s) of the hazard
• parent – Parent hazard
• ci – System(s) or sub-system(s) this hazard is related to
• same_scenario_as – The related causes are the same as the ones of another hazard.
86 of 101 23.18. tsc_functional_traceability

23.20 tsc_hazard_log
class tsc_sphinx.tsc_sphinx.tsc_hazard_log
This directives generates the hazard log related to one or many configuration items.
Parameters
• ci – CI for which to generate the hazard log.
• with_ci_hierarchy – Select also all the ci composed Boolean values must be
‘True’ or ‘False’ Default value is True.
• hazards_only – Only show hazards, not mitigations. Boolean values must be ‘True’
or ‘False’ Default value is False.
• default_mitigation_stakeholder – This will be reported as stakeholder in
the hazard log if a given mitigation has none. Default value is -.
• na_excluded – Only show applicable hazards, not the not applicable. Boolean values
must be ‘True’ or ‘False’ Default value is False.
23.21 tsc_interface_traceability_matrix
class tsc_sphinx.tsc_sphinx.tsc_interface_traceability_matrix
Create a traceability matrix between interfaces and test_case/test_scenario
Parameters
• justification – Add in the column justification the justification for each in-
terface not covered. The format was: InterfaceName1#Justification1, Interface-
Name2#Justification2. . .
23.22 tsc_limitation
class tsc_sphinx.tsc_sphinx.tsc_limitation
Documents a limitation on a baseline.
Parameters
• id – Unique identifier of the limitation
• ci – The CI being targeted by the limitation
• source – The artifact where the limitation originates from.
• is_safety_related – Requirement is safety related. Safety related status can be
23.20. tsc_hazard_log 87 of 101

• is_cybersecurity_related – Requirement is cybersecurity related. Cyberse-

curity related status can be one of the following: Undefined, Yes, No. Default value is
Undefined.
• mitigations – Mitigation requirement to which the limitation is transferred.
23.23 tsc_mode
class tsc_sphinx.tsc_sphinx.tsc_mode
Documents a functional mode of a system.
23.24 tsc_qa_report
class tsc_sphinx.tsc_sphinx.tsc_qa_report
This presentation directive displays a report of all QA findings generated during the documentation genera-
tion.
23.25 tsc_part
class tsc_sphinx.tsc_sphinx.tsc_part
This directive declares a part. A part is a uniquely identifiable object that can be ordered, documented and/or
installed.
Parameters
• ci – The CI representing this part
• supplier – The supplier of the part
• sub_parts – Sub-parts of the part
• part_number – The unique number identifying this part on the supplier side.
• height_mm – For physical parts: the height of the part.
• width_mm – For physical parts: the width of the part.
• depth_mm – For physical parts: the depth of the part.
• length_mm – For physical parts: the length of the part.
• weight_kg – For physical parts: the weight of the part.
• power_watt – For physical parts: the power consumed by the part.
• power_input – For physical parts: the power input tolerated by the part.
• datasheet – Artifact providing the datasheet of the part.
• manual – Artifact providing the applicable manual(s).
• cad_model – Artifact providing the 2D or 3D model of the part
• certification_kit – Artifact providing certification material for the part
• baseline – If applicable, the CI baseline version this part represents.
88 of 101 23.23. tsc_mode

23.26 tsc_part_list
class tsc_sphinx.tsc_sphinx.tsc_part_list
Produces a list of all parts composing a given part.
Parameters
• part – The part
• excel_only_in_html – Don’t show the full table in the HTML. Boolean values
• hide_navigator – Don’t show the part navigator. Boolean values must be ‘True’
23.27 tsc_pbs
class tsc_sphinx.tsc_sphinx.tsc_pbs
This directive inserts the product breakdown structure of a CI in the document.
Parameters
• ci – The top CI to build a PBS for.
• excel_only_in_html – Don’t show the full table in the HTML. Boolean values
• hide_navigator – Don’t show the CI navigator (in html). Boolean values must be
‘True’ or ‘False’ Default value is False.
23.28 tsc_raci
class tsc_sphinx.tsc_sphinx.tsc_raci_matrix
This directive builds a responsibility assignment matrix for the current document.
Parameters
one of the following: A4,A3_Landscape
• activity_label_size – Size of column that include the title of the activity De-
fault value is 12.
23.26. tsc_part_list 89 of 101

23.29 tsc_recap_table
class tsc_sphinx.tsc_sphinx.tsc_recap_table
This presentation directive creates a table listing the instances of a given directive.
The headings of the table use the safe bullet text representation specified for each field. For the argument
column, the table header is “Description”.
Parameters
• directive_name – The name of the directive to be recapitulated in a table
• header_fields – The name of the fields to be displayed in the columns of the table.
It must be a python list.
• ref_by_fields – The name of the ref_by fields to be displayed in columns on the
right of the table. It must be a python list.
• colwidths – The column widths. This must be a python list of integers of the same
size as the header_fields list. If size differs, columns will be assumed to have all the
same size
• sort_key – The name of the field to be used as sort key in the table.
23.30 tsc_req
class tsc_sphinx.tsc_sphinx.tsc_req
Specifies a requirement, in compliance with TSC requirement management plan.
Parameters
• id – Unique requirement ID. The ID given must be unique among all requirements that
will be analyzed during documentation generation. Generation will fail in case it is not
the case.
• status – Status of the requirement. Status of requirements can be one of the follow-
ing: Applicable, Under Evaluation, Unsupported. Default value is Applicable.
• allocated_to – Comma-separated list of CIs this requirement is allocated to.
• source – Comma-separated list of requirement IDs this requirement originates from.
• source_justification – A text providing a justification for the requirement
source traceability.
• verification – Method to be used to verify this requirement. Verification method
for requirements can be one of the following: Review, Test, Analysis, Model.
• stakeholders – Comma-separated list of stakeholders for this requirement.
• exported_to – Comma-separated list of stakeholders this requirement is exported
to.
• functions – Comma-separated list of functions allocated to this requirement.
• class – Class of the requirement. Requirements classes can be one of the following:
Functional, Architecture, Environmental, Performance, Rams, Standards, Documenta-
tion, Process, Miscellaneous, Verification_Goal. Default requirement class is Miscella-
neous unless it is attached to a function (Functional).
90 of 101 23.29. tsc_recap_table

• is_safety_related – Requirement is safety related. Safety related status can be

• is_cybersecurity_related – Requirement is cybersecurity related. Cyberse-
curity related status can be one of the following: Undefined, Yes, No. Default value is
Undefined.
• target_safety_case – If this requirement is a mitigation, documents the artifact
(e.g. safety case) where it should be demonstrated.
• is_mitigation – Specifies that the requirement is a mitigation. Mitigations do
not appear in requirement specs, but should be traced by some other implementing
requirements. Boolean values must be ‘True’ or ‘False’ Default value is False.
• mitigation_status – If this requirement is a mitigation, documents the safety
level. Safety status can be one of the following: In Analysis, Pending, In progress,
Implemented, Implemented And Verified, To be exported, Exported, Not Applicable.
Default value is Undefined.
• mitigation_evidence – If this requirement is a mitigation, documents the evi-
dence used to derive its status.
• compliance_level – Compliance level required for this requirement Compliance
levels can be one of the following: P1, P2, P3. Default value is P1.
• bookmark – List of bookmark that reference this requirement. Create a link between
the requirement and his bookmark in the doc. This field is calculated and should not be
set. If set it will be ignored.
23.31 tsc_req_list
class tsc_sphinx.tsc_sphinx.tsc_req_list
Insert a table listing the requirements of a given configuration items in the document. A link to an Excel
version is also provided.
Parameters
• ci – CI for which to generate a requirement list.
• source_ci – A list of CIs used to filter the requirements in the spec. Only require-
ments having these CIs as parent will be retained.
• exported_to – Stakeholder for which exported requirements shall be included in the
list.
23.32 tsc_req_spec
class tsc_sphinx.tsc_sphinx.tsc_req_spec
Insert a requirement specification for a given configuration item in the document. Functional requirements
are sorted by functions, then non-functional requirements are sorted by class. Exported requirements are
sorted by stakeholders. Finally, unsupported requirements are listed unsorted.
Parameters
• ci – CI for which to generate a requirement spec.
23.31. tsc_req_list 91 of 101

• source_ci – A list of CIs used to filter the requirements in the spec. Only require-
ments having these CIs as parent will be retained.
23.33 tsc_req_traceability_matrix
class tsc_sphinx.tsc_sphinx.tsc_req_traceability_matrix
Create a requirement traceability matrix.
Parameters
• ci – CI for which to generate a traceability matrix.
23.34 tsc_role
class tsc_sphinx.tsc_sphinx.tsc_role
Parameters required_skills – A comma separated list of tsc_skill IDs.
23.35 tsc_stakeholder
class tsc_sphinx.tsc_sphinx.tsc_stakeholder
Parameters
• organization – Name of the organization this stakeholder belongs to.
• roles – Roles this stakeholder has in the organization it belongs to.
• contact_details – Contact details for this stakeholder. Typically, a person that
can represent the stakeholder’s interests
• tsc_contact – Contact point for this stakeholder at TSC.
• availability – How easy it is to contact the stakeholder.
• domain – General domain of expertise of the stakeholder.
• expertise_level – Level of expertise of the stakeholder.
• goal – Goal pursued by the stakeholder with TSC products or services.
23.36 tsc_static_verification
class tsc_sphinx.tsc_sphinx.tsc_static_verification
This directive identifies a verification to perform.
Parameters
• requirements – Requirement verify by this verification.
• interface – Interface tested by this test case.
• type – The type of the verification (e.g. Code reading, Computation, etc.)
• artifact – Artifact on which verification must be made
92 of 101 23.33. tsc_req_traceability_matrix

• ci – Configuration Item on which verification must be made
23.37 tsc_static_verification_result
class tsc_sphinx.tsc_sphinx.tsc_static_verification_result
This directive identifies a verification result.
Parameters
• verification – Verification to be performed to product this result
• who – Person who performed the verification
• result – If this result is OK, JOK (Justified OK) or NOK Result must be ‘OK’, ‘JOK’
or ‘KO’
• justification – Justification of the JOK or a quick explanation of what was NOK.
23.38 tsc_sub_part_data
class tsc_sphinx.tsc_sphinx.tsc_sub_part_data
This directive documents the relationship between a part and its subpart. Typically, this can be used to
document quantities.
Parameters
• part – The part
• sub_part – The sub part
• quantity – The quantity of sub parts composing the part Quantity must be an integer
value or custom Default value is 1.
• info – Information about the subpart within the context of the part.
23.39 tsc_supplier
class tsc_sphinx.tsc_sphinx.tsc_supplier
This directive declares a supplier.
Parameters iso_9001_certificate – A string.
23.40 tsc_sw_standard_conformity
class tsc_sphinx.tsc_sphinx.tsc_sw_standard_conformity
This directive declares an entry in a software standard for which an analysis shall be performed by TSC and
recorded.
Parameters
• standard – The name of the standard
• index – Index of entry in standard
• id – Identifier of entry in standard
• category – Category of entry in standard
• analysis – TSC’s analysis of entry to be recorded
• requires_action – 1 if the analysis requires action from TSC
23.37. tsc_static_verification_result 93 of 101

23.41 tsc_test_case
class tsc_sphinx.tsc_sphinx.tsc_test_case
This directive identifies a test case.
Parameters
• requirements – Requirement tested by this test case.
• interface – Interface tested by this test case.
• family – family of the test case (Functional, Dis-functional,. . . ).
• parameters – List of parameter and there value for this test case.
• pre-condition – Precondition needed to execute this test case.
• required_configuration – The required configuration to execute this test case
(Complete (the whole configuration),Partial (to be detailed) . . . )
• action – Artifact listing the action to be performed and the expected result for each
step of the test case.
23.42 tsc_test_case_result
class tsc_sphinx.tsc_sphinx.tsc_test_case_result
This directive identifies a test case result.
Parameters
• test_case – Test Case to be performed to product this result
• who – Person who performed the test
• result – If this result is OK, JOK or KO Result must be ‘OK’, ‘JOK’ or ‘KO’
• issue – the issue number is the result is NOK
• justification – Justification of the JOK or a quick explanation of what was KO.
23.43 tsc_test_scenario
class tsc_sphinx.tsc_sphinx.tsc_test_scenario
This directive identifies a test scenario.
Parameters
• requirements – Requirement tested by this test scenario.
• source – The eventual source code of a program that implements the test scenario
• source_signature – The signature of the source code, if source is documented.
Default value is None.
• ci – Configuration item to be tested.
• family – family of the test scenario (Functional, Dis-functional,. . . ).
• test_cases – Interface tested by this test scenario.
• parameters – List of parameter and there value for this test case.
• pre-condition – Precondition needed to execute this test scenario.
• required_configuration – The required configuration to execute this test sce-
nario (Complete (the whole configuration),Partial (to be detailed) . . . )
94 of 101 23.41. tsc_test_case

• action – Link to the script listing the action to be performed and the expected result
for each step of the test scenario.
23.44 tsc_test_scenario_result
class tsc_sphinx.tsc_sphinx.tsc_test_scenario_result
This directive identifies a test scenario result.
Parameters
• test_scenario – Test Case to be performed to product this result
• who – Person who performed the test
• result – If this result is OK, JOK or KO Result must be ‘OK’, ‘JOK’ or ‘KO’
• issue – the issue number is the result is NOK
• justification – Justification of the JOK or a quick explanation of what was KO.
23.45 tsc_tool_class
class tsc_sphinx.tsc_sphinx.tsc_tool_class
This directive declares a tool Classification.
A Tool Classification is an element that permit to justify the classification of the tool
Parameters
• ci – Configuration Item that identify the tool
• sub_module – Sub module of the tool concerned the classification
• version – Version and revision of the tool subject to the classification
• classification – The classification of the tool EN50128 class of the tool allowed
values
• license_type – Type of license
• use_case – Description of Use case for this tool
• required_skills – List of the required skill for the tools
• administrator – A comma separated list of tsc_role IDs.
23.46 tsc_tool_list
class tsc_sphinx.tsc_sphinx.tsc_tool_list
This directive inserts a tool list in the document.
Parameters
23.44. tsc_test_scenario_result 95 of 101

23.47 tsc_verification_traceability_matrix
class tsc_sphinx.tsc_sphinx.tsc_verification_traceability_matrix
Create a traceability matrix between requirements and test_case/test_scenario
Parameters
• ci – CI for which to generate a traceability matrix.
• justification – Add in the column justification the justification for each re-
quirement not covered. The format was: RequirementId1#Justification1, Requiremen-
tId2#Justification2. . .
23.48 tsc_xlsx_data
class tsc_sphinx.tsc_sphinx.tsc_xlsx_data
This meta-directive reads lines from an Excel sheet as if they were individual directive declarations, where
the value of each option are given in a column.
• The first line must contains the name of the TSC option corresponding to the column. The reader will
ignore columns after the first column with an empty cell on the first line.
• The last line must contain the special value TSC_EXCEL_EOF. If this line does not exist, then the
reader will attempt to read all the lines up to the value specified in the max_row parameter. When this
happens, the builder will fail to prevent data from being lost.
• There must be one column with the name ‘is_ignored’. This column can be used to instruct the Excel
reader to skip a line. Enter ‘Yes’ for the line to be ignored. By default, the line is not ignored.
Parameters
• directive_name – The name of the directive to be instantiated
• file – Path to the excel file. First sheet will be read.
• max_row – Maximum number of line to be parsed Default value is 10000.
23.49 Experimental features

class tsc_sphinx.tsc_sphinx.tsc_test
This directive identifies a test case.
Parameters validates – Requirement validated by this test case.
class tsc_sphinx.tsc_sphinx.tsc_test_suite
This directive identifies a test suite.
Parameters test_cases – Test cases making the test suite.
96 of 101 23.47. tsc_verification_traceability_matrix

23.50 Obsolete directives

class tsc_sphinx.tsc_sphinx.tsc_boq
This directive inserts a bill of quantity in the document.
The BoQ displays, for a given CI, all its direct child CIs with their quantity and information.
Parameters ci – The CI which BoQ is to be reported
class tsc_sphinx.tsc_sphinx.tsc_skill
class tsc_sphinx.tsc_sphinx.tsc_employee
This directive creates an employee of the company.
Personal data, such as the date of birth, gender, payroll and other are managed by HR in confidential manner
using a dedicated system. We only document the payroll ID so that HR can match data.
Parameters
• email – A string.
• joined – A string.
• first_name – A string.
• last_name – A string.
• payroll_id – A string.
• positions – A comma separated list of tsc_position IDs.
• extra_roles – A comma separated list of tsc_role IDs.
class tsc_sphinx.tsc_sphinx.tsc_project
This directive declares a project.
Parameters
• id – Unique project ID.
• project_manager – Manager in charge of leading the project.
• architect – Technical authority on the project.
• supplier – Supplier of the project.
• supplier_ref – Reference used for the project on supplier side.
• supplier_pm – Project manager on supplier side.
• start_date – Start date of the project Correct date format is DD/MM/YYYY
• end_date – End date of the project Correct date format is DD/MM/YYYY
• analytical_1 – Data used to manage analytical accounting.
• is_archived – Project is finished and has been archived. Boolean values must be
‘True’ or ‘False’
class tsc_sphinx.tsc_sphinx.tsc_position
This directive declares a position within the organization of the company. A position may grant certain
roles. In addition, a position reports to another position.
Parameters
• reports_to – A comma separated list of tsc_position IDs.
• roles – A comma separated list of tsc_role IDs.
class tsc_sphinx.tsc_sphinx.tsc_experience
23.50. Obsolete directives 97 of 101

Parameters
• of – A comma separated list of tsc_employee IDs.
• from – A string.
• to – A string.
• skill – A comma separated list of tsc_skill IDs.
class tsc_sphinx.tsc_sphinx.tsc_training
This directive records a training that an employee received.
Parameters
• of – A comma separated list of tsc_employee IDs.
• date – A string. Correct date format is DD/MM/YYYY
• skill – A comma separated list of tsc_skill IDs.
• trainer – Optional information on the trainer.
• coaching – Specify if the training included coaching. Boolean values must be ‘True’
• proof – Path to an evidence of the training (scan of certificate, . . . ) or a link to a Gitlab
issue
• proof_expiration_date – A string. Correct date format is DD/MM/YYYY
class tsc_sphinx.tsc_sphinx.tsc_risk
This directive represents a risk.
Parameters
• category – A string.
• possible_cause – A string.
• possible_impact – A string.
• severity_grade – A string.
• probability – A string.
class tsc_sphinx.tsc_sphinx.tsc_purchase_order
This directive represents a purchase order.
Parameters
• id – Unique purchase order ID. The ID given must be unique among all PO
• supplier – Supplier on the receiving end of the purchase order
• date – Date the PO was submitted to the supplier.
• requestor – The TSC manager who has requested the purchase order.
• approver – The TSC manager who has approved the purchase order.
• project – The project this purchase order is attached to (optional).
• file – Name of the PO document
• url – URL to the PO file (optional).
class tsc_sphinx.tsc_sphinx.tsc_it_computer
Parameters
• supplier – A string.
• location – A string.
• administrator – A string.
98 of 101 23.50. Obsolete directives

class tsc_sphinx.tsc_sphinx.tsc_verification
This directive declares a verification activity on a version of an artifact. Such directive is intended to be
inserted in verification reports.
Parameters
• artifact_version – The name and version of the artifact(s) verified
• date – Date of the verification
• by – Who did the verification
23.50. Obsolete directives 99 of 101

INDEX
:caption: (directive option) N

code-block (directive), 26 numref (role), 19
:dedent: (directive option)
code-block (directive), 26 O
:emphasize-lines: (directive option)
only (directive), 25
code-block (directive), 26
:force: (directive option) R
:lineno-start: (directive option) ref (role), 18
:linenos: (directive option)
T
code-block (directive), 25 term (role), 19
:name: (directive option) toctree (directive), 20
code-block (directive), 26 tsc (role), 31
TSC configuration value
C tsc_builder_filter, 74
tsc_latex_variables, 74
tsc_activity (class in tsc_sphinx.tsc_sphinx), 78
:caption: (directive option), 26
tsc_allocate (class in tsc_sphinx.tsc_sphinx), 82
:dedent: (directive option), 26
tsc_artifact (class in tsc_sphinx.tsc_sphinx), 78
:emphasize-lines: (directive option), 26
tsc_artifact (role), 31
:force: (directive option), 26
tsc_artifact_history (class in
:lineno-start: (directive option), 25
tsc_sphinx.tsc_sphinx), 80
:linenos: (directive option), 25
tsc_artifact_list (class in
:name: (directive option), 26
D tsc_artifact_status (class in
doc (role), 19 tsc_artifact_version (class in
F tsc_assumption (class in tsc_sphinx.tsc_sphinx),
figure (directive), 23 81
tsc_attach (class in tsc_sphinx.tsc_sphinx), 82
G tsc_baseline (class in tsc_sphinx.tsc_sphinx), 82
glossary (directive), 27 tsc_boq (class in tsc_sphinx.tsc_sphinx), 97
tsc_builder_filter
I TSC configuration value, 74
image (directive), 22 tsc_cause (class in tsc_sphinx.tsc_sphinx), 83
include (directive), 24 tsc_ci (class in tsc_sphinx.tsc_sphinx), 83
tsc_ci_artifact (class in tsc_sphinx.tsc_sphinx),
L 84
literalinclude (directive), 24 tsc_ci_component (class in
M tsc_coding_rule (class in tsc_sphinx.tsc_sphinx),
84
math (directive), 27
tsc_employee (class in tsc_sphinx.tsc_sphinx), 97
math (role), 19
tsc_experience (class in tsc_sphinx.tsc_sphinx),
97
100 of 101 Index

tsc_function (class in tsc_sphinx.tsc_sphinx), 84 tsc_tool_class (class in tsc_sphinx.tsc_sphinx),

tsc_function_traceability_matrix (class 95
in tsc_sphinx.tsc_sphinx), 86 tsc_tool_list (class in tsc_sphinx.tsc_sphinx), 95
tsc_functional_variable (class in tsc_training (class in tsc_sphinx.tsc_sphinx), 98
tsc_sphinx.tsc_sphinx), 85 tsc_verification (class in
tsc_hazard (class in tsc_sphinx.tsc_sphinx), 86 tsc_sphinx.tsc_sphinx), 99
tsc_hazard_log (class in tsc_sphinx.tsc_sphinx), tsc_verification_traceability_matrix
87 (class in tsc_sphinx.tsc_sphinx), 96
tsc_interface_traceability_matrix tsc_xlsx_data (class in tsc_sphinx.tsc_sphinx), 96
(class in tsc_sphinx.tsc_sphinx), 87 TSCJSONBuilder (class in tsc_sphinx.builder), 73
tsc_it_computer (class in tsc_sphinx.tsc_sphinx),
98
tsc_latex_variables
TSC configuration value, 74
tsc_limitation (class in tsc_sphinx.tsc_sphinx),
87
tsc_mode (class in tsc_sphinx.tsc_sphinx), 88
tsc_part (class in tsc_sphinx.tsc_sphinx), 88
tsc_part_list (class in tsc_sphinx.tsc_sphinx), 89
tsc_pbs (class in tsc_sphinx.tsc_sphinx), 89
tsc_position (class in tsc_sphinx.tsc_sphinx), 97
tsc_project (class in tsc_sphinx.tsc_sphinx), 97
tsc_purchase_order (class in
tsc_qa_report (class in tsc_sphinx.tsc_sphinx), 88
tsc_raci_matrix (class in tsc_sphinx.tsc_sphinx),
89
tsc_recap_table (class in tsc_sphinx.tsc_sphinx),
90
tsc_req (class in tsc_sphinx.tsc_sphinx), 90
tsc_req_list (class in tsc_sphinx.tsc_sphinx), 91
tsc_req_spec (class in tsc_sphinx.tsc_sphinx), 91
tsc_req_traceability_matrix (class in
tsc_risk (class in tsc_sphinx.tsc_sphinx), 98
tsc_role (class in tsc_sphinx.tsc_sphinx), 92
tsc_skill (class in tsc_sphinx.tsc_sphinx), 97
tsc_stakeholder (class in tsc_sphinx.tsc_sphinx),
92
tsc_static_verification (class in
tsc_static_verification_result (class in
tsc_sub_part_data (class in
tsc_supplier (class in tsc_sphinx.tsc_sphinx), 93
tsc_sw_standard_conformity (class in
tsc_test (class in tsc_sphinx.tsc_sphinx), 96
tsc_test_case (class in tsc_sphinx.tsc_sphinx), 94
tsc_test_case_result (class in
tsc_test_scenario (class in
tsc_test_scenario_result (class in
tsc_test_suite (class in tsc_sphinx.tsc_sphinx),
96
Index 101 of 101


TSC Sphinx Doc Manual V4.0

Uploaded by

Copyright:

Available Formats

You might also like

TSC Sphinx Doc Manual V4.0

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

TSC Sphinx Doc Manual V4.0

Uploaded by

Copyright:

Available Formats

TSC Sphinx Extension User Manual

1 Revision history [artifact history] 3

10 Product Breakdown Structure 43

15 Roles and activities 59

16 Software & Tools 62

17 Verification and Testing 63

REVISION HISTORY [ARTIFACT HISTORY]

This artifact version is: V4.0

This artifact signature: 05a0a6b4abdd927fe30de7643a36765158c9b1bc

Name Description Date Author Signature MR

1. Revision history [artifact history] 3 of 101

The document is structured as follows:

• Spell checking describes the spell checking features;

2.4 Applicable documents

[TSC-SPHINX-MANUAL-R0-GLOSSARY] TSC glossary [id: glossary]

2.5 Reference documents

[TSC-SPHINX-MANUAL-R3-ARCADIA] Model-based System and Architecture Engineering with the Arcadia

2.6 Terms and definition

2.7 Artifact definition

2.4. Applicable documents 5 of 101

A long time ago in a galaxy far far away...

.. tsc_req:: The text shall be displayed in blue over black background

The root directory of a Sphinx documentation contains two files:

Note: More on directives

6 of 101 3. Getting started

You add documents listing them in the content of the directive:

You will need to type command in a command prompt.

The version number should be displayed, for instance:

git version 2.21.0.windows.1

The version number should be displayed, starting with 3. For instance:

A Linux (e.g. Ubuntu 64 bits) running Python3 is required.

git clone https://gitlab.com/tsc-projects/tsc.git

Install the python packages:

pip install -r requirements.txt

Install the dependencies on Alpine Linux:

Install the dependencies on Ubuntu 18.04:

sudo apt install make cmake aspell-en texlive texlive-binaries texlive-extra-utils

We use CMake as our build tool. To run it:

Other possible targets include:

4.2. On Linux 9 of 101

Note: More specifically, download and run this http://mirror.ctan.org/systems/texlive/tlnet/install-tl-windows.

git config --global core.autocrlf false

5. Clone the last version of the tsc repository:

git clone https://gitlab.com/tsc-projects/tsc.git

6. Install all python build tools as follows:

7. Test your windows build installation:

9. To build the JSON export of the documentation:

10. To build the PDF documentation:

10 of 101 4.3. On Windows

The result should look as shown in the following figure.

5. Training ground 11 of 101

6.1 Quick run

6.1.1 Hello world

Titles are identified with an underline repeating a

Paragraphs are simply blocks of texts separated by a

This will be a chapter in the document

This will be a sub-section of chapter 1.

This will be another chapter. Sphinx knows

This appears in bold too

This will appear in italics