.. comment
	
	all inline tags to start with _help_prereq_
	
.. index:: How to; Rules for editing pages


.. _help_prereq_top:


Prerequisits for contributing and editing these pages
#####################################################

.. include:: /pages/common/pageunderconstruction.txt
	:start-line: 3
	
.. contents:: Contents:
		:local:
		:depth: 1
		:backlinks: top
	
******************
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

.. rst-class:: expand

================================
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:

#. create a folder where the virtual environment is to be stored. e.g. ::
	
	C:\Users\Public\Documents\PythonVirtualEnv
	
#. 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
	
#. Activate the environment e.g. ::

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

#.	

	.. 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.
			
#. 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>
			

#. 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 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


.. _help_prereq_editing:

****************
Editing content
****************

This documentation contains :ref:`rules specific to these pages <help_rules_top>` and a brief introduction to :ref:`editing pages <help_edit_top>` or use the 
`Sphinx reStructuredText Primer <http://www.sphinx-doc.org/en/stable/rest.html#rst-primer>`_ 
for a more in-depth introduction to reStructuredText and 
`Sphinx Markup Constructs <http://www.sphinx-doc.org/en/stable/markup/index.html#sphinxmarkup>`_ 
for a full list of markup added by Sphinx. 

========================
Build this documentation
========================

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

#. 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>
	
#. (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) 
	
#. 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
	
.. figure:: /images/help/setupnewsphinx01.png

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.

.. sectionauthor:: |Judith Crockford|

.. include:: /keywords.rst