Contributing¶
This document provides guidelines for people who want to contribute to the documentation-style-guide-sphinx project.
Create tickets¶
Please use the bugtracker [1] before starting some work:
check if the bug or feature request has already been filed. It may have been answered too!
else create a new ticket.
if you plan to contribute, tell us, but don’t wait for us! So that we are given an opportunity to discuss, join forces or give feedback as soon as possible.
Fork and branch¶
Work in forks and branches.
Prefix your branch with the ticket ID corresponding to the issue. As an example, if you are working on ticket #23 which is about headings convention, name your branch like
23-headings.
Download and install¶
System requirements:
Python [2] version 2.6 or 2.7.
Note
The provided Makefile uses
pythoncommand. So you may use Virtualenv [3] to make sure the activepythonis the adequate one.
Execute:
git clone git@github.com/benoitbryon/documentation-style-guide-sphinx.git
cd documentation-style-guide-sphinx/
make install
If you cannot execute the Makefile, read it and adapt the few commands it
contains in the install section to your needs.
Edit documents¶
They said “Eat your own dog food”, so follow style guide for Sphinx-based documentations [4].
In your commit messages, reference the ticket with some refs #TICKET-ID
syntax.
Test and build¶
Tests and builds will automatically be triggered before commit:
tests include the build of documentation and README as HTML.
a Git pre-commit hook [5] is installed during Download and install.
If you want to run them manually, use the provided Makefile:
run tests with
make testsbuild documentation with
make documentation-buildbuild README with
make README-build