Writing documentation¶
Good documentation is just as important as tests. GLAMkit pull requests should endeavour to include and/or update documentation where appropriate.
GLAMkit documentation is written in ReStructured Text (ReST) format, and compiled to HTML using Sphinx. Documentation is hosted on ReadTheDocs.
Conventions¶
- Include examples so new contributors can get started quickly.
- Keep the Changelog up to date. Describe features, not implementation details, except for backwards incompatible changes.
- We’re aiming to document all non-private modules, classes and functions in
GLAMkit. The easiest way to do this is in the docstrings of the class, with
an
automodule
call out from this document structure. - Titles should be sentence case.
- File extensions are
.rst
and hard-wrapped at 80 columns.
Setup (macOS)¶
Install Homebrew:
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Install system dependencies:
$ brew install git pandoc pyenv pyenv-virtualenv
$ cat <<EOF >> ~/.bash_profile
# Configure pyenv.
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
EOF
Clone the repository and change directory:
$ git clone https://github.com/ic-labs/django-icekit.git
$ cd django-icekit/docs
Create a virtualenv:
$ pyenv install 2.7.13
$ pyenv virtualenv django-icekit-docs 2.7.13
$ pyenv local django-icekit-docs
Install Python dependencies:
(django-icekit-docs)$ pip install -r requirements.txt
Building HTML documentation¶
Run a server to autobuild and preview the docs (open http://icekit-docs.lvh.me:8000 in a browser):
(django-icekit-docs)$ sphinx-autobuild . _build_html
Or build static HTML docs (open _build/index.html
in a browser):
(django-icekit-docs)$ make html