This document contains information to support uniform, high quality, and efficient development of Makahiki.
All code should pass Pylint, PEP 8, and the current set of Makahiki unit tests. To run them individually:
% cd makahiki/
% scripts/run_pylint.sh
% scripts/run_pep8.sh
% python manage.py test
To simplify quality assurance, there is a script called verify.py that runs all of these scripts:
% cd makahiki/
% scripts/verify.py
If all return successfully, then verify.py returns normally and no output is printed. If there are any errors, the output associated with the unsuccessful tools is printed and verify.py returns with an error code.
It is good practice to run verify.py prior to pushing your code to the master branch at github.
Be patient: verify takes 10 seconds or more to complete.
To obtain a coverage report on the test cases:
% scripts/coverage.py
The report will be generated into the directory htmlcov/. Open index.html to browse. Click the coverage column to sort, and click on a module to see which lines were tested and which lines were not.
Documentation strings should be enclosed in triple double quotes.
Documentation strings should be formatted using reStructuredText format so that they can be easily processed using the Sphinx autodoc extension.
The first line of a documentation string (i.e. the line containing the open triple double quote) should contain a one sentence summary of the purpose of the program unit (module, class, function, variable, etc.)
If one sentence suffices to document the program unit, then the closing triple double quote should appear on the same line.
Otherwise there should be a blank line followed by additional lines of documentation. In this case, the closing triple double quote appears on its own line.
Every module (i.e. .py file) should have a documentation string explaining its purpose and (if relevant) client interface.
The module documentation string should not specify the file name.
For example, here is an example docstring for the apps/pages/views.py module:
"""Provides the top-level rendering functions for all makahiki pages.
This module handles all requests for Makahiki pages. It handles
authentication and contains the code to dynamically render the custom
configured pages for any particular site.
"""
All functions should have a documentation string explaining its purpose and documenting parameters and any return values.
See the Info field lists page for helpful information on how to format parameter lists and return values appropriately.
For example, here is an example docstring for the index(request) method appearing in the apps/pages/views.py module:
"""Process the request, dynamically generating the page as specified in page_settings.
:param request: The django request object.
:return: The response object for the page.
"""
All variables should have a documentation string explaining its purpose and who might reference it.
Variables should be documented by a documentation string immediately following the variable declaration. For example:
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': 'dev.db',
'USER': '',
'PASSWORD': '',
}
}
"""Specifies the default database, required by Django."""