Skip to content

Latest commit

 

History

History
77 lines (58 loc) · 3.15 KB

CONTRIBUTING.rst

File metadata and controls

77 lines (58 loc) · 3.15 KB
Raw

Contributing

Contact Information

You can interact with us through:

Code Guidelines

  • Please, use PEP8.
  • Write tests for every feature you add or bug you solve (preferably use test-driven development).
  • Commented code is dead code.
  • Name identifiers (variable, class, function, module names) with readable names (x is always wrong).
  • Use Python's new-style formatting ('{} = {}'.format(a, b) instead of '%s = %s' % (a, b)).
  • All #TODO should be translated in issues (use our GitHub issue system).
  • Run all tests before pushing (just execute make test).
  • Try to write Python3-friendly code, so when we decide to support both Python2 and Python3, it'll not be a pain.

Git Usage

Generating Documentation

Currently we are using the repository pypln.org to store PyPLN's website and docs, so the method described below is not needed anymore. We just need to make the documentation, move all files to pypln.org repo, commit and then push.

We use the script make-docs.sh to generate documentation and it's served by GitHub Pages. As we need to put only the static documentation files on branch gh-pages, our script does the job of:

  • Stash (including untracked files) any non-commited modifications on current branch;
  • Checkout to develop branch;
  • Run sphinx and epydoc to generate documentation;
  • Copy generated documentation to another place (/tmp/pypln-docs);
  • Check out to branch gh-pages;
  • Copy the static files to repository, add them and commit;
  • Checkout back to the branch you were before running the script;
  • Unstash the changes.

You can also generate documentation from your current branch (instead of develop) or do not commit it (only generate). Please run ./make-docs -h to know all the available options.

Note: epydoc's Bug

If you get an exception when building documentation, probably it's an epydoc bug. Please read this post on StackOverflow and apply the proposed patch. Sorry, but it looks like it is not maintained anymore.

Note: we will try to move from epydoc to Sphinx in a near future due to this problem.