The Open-PSA Model Exchange Format

This repository hosts source text files for the Open-PSA Model Exchange Format.

Building

Note that no dependency is required to edit the text source of the standard; a basic text editor suffices to work with the source files. All building is done automatically on Travis-CI upon your pull request to verify successful generations in various target formats.

A list of dependencies:

Package	Minimum Version
Python	2.7 or 3.4
Sphinx	1.5.1
sphinx_rtd_theme	0.1.10
Pygments LaTeX Inkscape git zip	2.2

To install all the dependencies with apt and pip (assuming already installed Python and git):

sudo apt-get install texlive{,-{fonts-recommended,latex-extra,xetex}} inkscape
sudo pip install sphinx sphinx_rtd_theme

To generate a PDF document:

make latexpdf

To generate HTML files (the website at the gh-pages branch):

make html

reST Style

• Semantic Linefeeds (i.e., one sentence per line)
• No UTF-8 math characters or symbols (use inline LaTeX math instead)
• Part # overlined and underlined
• Chapter * overlined and underlined
• Section underlining and order =, -, ~, ^, +
• Point nesting and order -, *, +
• 4-space indentation
• 100 character line limit (except for links and paths)
• No trailing whitespace characters
• No tabs (spaces only)
• No excessive blank lines at the end of files
• One blank line after a header before its body
• Prefer two blank lines between sections with bodies

Reference Naming Conventions

Prepend a reference name with the type of the object (a la the Hungarian notation) for clarity and consistency of in-text references. If there's no prefix in a reference, the target is assumed to be the specification or section itself.

For example, an image (figure), table, XML description, RNC schema of the fault tree specification:

.. figure:: images/fault_tree.svg
    :name: fig_fault_tree

    Fault tree diagram


.. table:: The fault tree specification
    :name: table_fault_tree

    +-------+------+
    | Fault | Tree |
    +=======+======+


.. code-block:: rnc
    :name: schema_fault_tree

    fault_tree = graph


.. code-block:: xml
    :name: xml_fault_tree

    <define-fault-tree/>

To reference the fault tree specification itself:

.. _fault_tree:

**********
Fault Tree
**********

The fault tree specification, description, text, ...

Helpful Resources

• Sphinx reStructuredText Primer
• Spinx reST Miscellaneous
• reStructuredText User Documentation
• reST Cheat Sheet
• reST Quick Reference
• Short Math Guide for LaTeX
• RELAX NG Compact Tutorial

Workflow

1. Start by forking this repository and setting it as the upstream repository.
2. Create your topic branch from the master branch.
3. Keep in sync your origin master branch with the upstream master branch.
4. Keep your topic branch in sync with the master branch by merging or rebasing your topic branch on top of the master. Rebasing is highly recommended for streamlining the history. However, DO NOT rebase any commits that have been pulled/pushed anywhere else other than your own fork.
5. Submit your pull request from your topic branch to the upstream master branch.
6. Your pull request will be reviewed by another editor before merging.

Git Resources and Best Practices

• Git SCM
• Writing Good Commit Messages
• On Commit Messages
• Atomic Commit
• Branching Model