Prerequisits for contributing and editing these pages

Warning

This page is under construction.

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

Required Software

Python 2.7.3

pip 1.2.1

To build this documentation you will also need the following python packages:

pip install sphinx==1.5.5

pip install sphinx_rtd_theme==0.2.5b1

pip install sphinxmark==0.1.19

Admin restrictions and firewalls

Some sites have PC administrator restrictions and/or firewalls restricting the use of pip install.

These instructions assume that Python is available on the PC, but not at the correct version, and without the additional packages.

The first step is to create a local virtual python environment:

1. create a folder where the virtual environment is to be stored. e.g.

   C:\Users\Public\Documents\PythonVirtualEnv
   

2. open a cmd window in this folder and type the following (where “pyenv” is the name of the virtual environment)

   C:\Users\Public\Documents\PythonVirtualEnv>virtualenv pyvenv --system-site-packages
   

3. Activate the environment e.g.

   C:\Users\Public\Documents\PythonVirtualEnv>pyvenv\Scripts\activate
   

4. Tip

   If you are not in the environment folder then type the full path e.g.

   C:\Users\Public\Documentation\STEPlib_User_Guide>C:\Users\Public\Documents\PythonVirtualEnv\pyvenv\Scripts\activate
   

   This is usual way to activate when using the virtual environment to build the Sphinx documentation.

5. the virtual environment should now be running and the prompt start with the virtual environment name as follows:

   (pyvenv) C:\Users\Public\Documentation\STEPlib_User_Guide>
   

6. install the updated Sphinx and other extensions from here. If there are firewall restrictions you will also need to use the –proxy arguement as shown below, replacing username and password with your credentials, and proxyname:proxyport with your proxy details (for Airbus UK these are uk0-proxylan-vip1.eu.airbus.corp:3128)

   (pyvenv)pip install sphinx==1.5.5 --proxy=http://username:password@proxyname:proxyport
   (pyvenv)pip install sphinx_rtd_theme==0.2.5b1 --proxy=http://username:password@proxyname:proxyport
   (pyvenv)pip install sphinxmark==0.1.19 --proxy=http://username:password@proxyname:proxyport
   

Git repository

See the Git Documentation Index for detailed instructions on using Git with STEPlib.

• Clone the gitlab project

  git@git2.boost-lab.net:documentation/STEPlib_User_Guide
  

• Make your own working branch, e.g. branchYourName

• Clone the repository

Editing content

This documentation contains rules specific to these pages and a brief introduction to editing pages or use the Sphinx reStructuredText Primer for a more in-depth introduction to reStructuredText and Sphinx Markup Constructs for a full list of markup added by Sphinx.

Build this documentation

You should now be able to create the build for this documentation.

1. Open a command window (cmd) in the documentation root folder. (The below shows the content of the cmd window)

   Microsoft Windows [Version 6.1.7601]
   Copyright (c) 2009 Microsoft Corporation.  All rights reserved.
   
   C:\Users\Public\Documentation\STEPlib_User_Guide>
   

2. (Optional) If using a virtual python environment, activiate it using the full path to the activate script (The below shows the content of the cmd window from step 1)

   Microsoft Windows [Version 6.1.7601]
   Copyright (c) 2009 Microsoft Corporation.  All rights reserved.
   
   C:\Users\Public\Documentation\STEPlib_User_Guide>C:\Users\Public\Documents\PythonVirtualEnv\pyvenv\Scripts\activate
   (pyvenv)
   

3. type make html (The below shows the content of the cmd window from step 1)

   Microsoft Windows [Version 6.1.7601]
   Copyright (c) 2009 Microsoft Corporation.  All rights reserved.
   
   C:\Users\Public\Documentation\STEPlib_User_Guide>C:\Users\Public\Documents\PythonVirtualEnv\pyvenv\Scripts\activate
   (pyvenv) C:\Users\Public\Documentation\STEPlib_User_Guide>make html
   

You should now be able to open the STEPlib_User_Guide\build\index.html in browser.

Publish the documentation

• commit your changes to your branch
• your branch must be merged into the release branch, the content approved and then merged into the master branch.
• the master branch is periodically published to this site.

Section author: Judith Crockford (AP243)