Contribution Guide¶
Developer setup¶
our development workflow is designed to be easy to setup. For this to occur, the following requirements are needed on the developers machine:
- Docker
- sudo access or be part of the group that can execute
docker - text editor (with new lines set to ``n`` not ``rn`` as you would see in windows)
Module¶
Setup the environment to use the local module baing developed.
Note: all commands run from the root of the repository directory.
Commands to setup build environment:
pip3 install virtualenv
python3 -mvirtualenv $PWD
bin/python -m pip install --upgrade --no-cache-dir pip
bin/python -m pip install --upgrade --no-cache-dir -r requirements.txt
bin/python setup.py develop install
test the module being developed
bin/python -B -m gitlab_management -h
Clean-up the environment
rm -Rf bin dist gitlab_management.egg-info lib include
Documentation¶
We use Sphinx for ducumentation. All documentation for the project lives in the docs/ directory within the repo. Documentation can be written in either RestructureText .rst or MarkDown .md files. Documentation for the modules however, is written within the code using NumPy style DocBook code comments. These comments are then rendered to .rst via the sphinx.ext.autodoc extension.
All Documentation is to be written in english. Since it depends on what dialect of english you speak, spelling can be different. The documentation spelling for plain speak (i.e. a sentance of text) will be Australian english.
Any additional pages are to be written in .md and placed in the directory docs/pages.
Further examples can be viewed here.
To document a property/variable add a single line comment underneath i.e.
DemoProperty:str = 'Property Value'
"""A single line describing the purpose of the property"""
template class documentation¶
The following is the template for a class. (delete sections that are not required)
class ExampleClassToDocument:
"""The summary line for a class docstring should fit on one line.
If the class has public attributes, they are not to be documented here. any parameters the class has as part of it's ``__init__`` should be documented in this section.
Example
-------
It should be assumed that a person using this class would have a working knowldege of python. However, if there are any intricacies that are outside of a simple string, this section should be used to explain how to use.
Parameters
----------
MandatoryParameter : str
[Single Line summary]
OptionalParameter : str, optional
[Single Line summary]
Attention
---------
Don't add an Attributes section to a class.
See Also
--------
"""
template method documentation¶
The following is the template for a method. (delete sections that are not required)
def ExampleMethod(MandatoryParameter:str, OptionalParameter:str=None):
"""[one line summary]
[detailed summary formated as paragraphs]
Example
-------
Examples can be given using either the ``Example`` or ``Examples``
sections. Sections support any reStructuredText formatting, including
literal blocks::
$ python example_numpy.py
Section breaks are created with two blank lines. Section breaks are also
implicitly created anytime a new section starts. Section bodies *may* be
indented:
Parameters
----------
MandatoryParameter : str
[Single Line summary]
OptionalParameter : str, optional
[Single Line summary]
NOTE
----
Notes and other tip boxes can be included in any section, just don't forget to indent.
Returns
-------
bool
True if successful, False otherwise.
"""
Building¶
Buiding of the docs is part of the validation stage of the build pipeline. The doc build, must complete without any warnings to be considered a pass.
Please build the docs locally before pushing to the repo, this will ensure that they are working befor being committed. After a local build the docs can be found in the repository directory under docs/_build/html/index.html
cd {Repo Directory}
docker run -e CI_PROJECT_DIR=/Repository -w /Repository -v $PWD:/Repository readthedocs/build:latest bash test/validation-build-docs.sh
.. Note: Substitute{Repo Directory}with the actual directory the repository was cloned to. However, you can also miss thecdcommand and adjust$PWDto be the{Repo Directory}.