LIVVkit

Contributing

LIVVkit is publicly developed within the LIVVkit project on GitHub and releases are packaged and distributed on PyPI and Anaconda Cloud.

Workflow

There are two encouraged ways to contribute to the development of LIVVkit:

1. Become a core developer

If you have many contributions and are planning on being an active developer, you may request to become a core developer by contacting Joseph H. Kennedy and briefely describing your intended contribution goals. Once approved, you will be given push access to the LIVVkit/LIVVkit repository (and any other needed repositories).

When developing the code, please follow the GitFlow workflow and make all your changes in a feature branch. Feature branches should follow the #-username-feature naming convention, where # indicates the issue being addressed (optional).

If you have any questions, concerns, requests, etc., open an issue in our issues queue, and we will help you out.

2. For outside contributions

For one-off or infrequent contributions, please use the Forking Workflow to add contributions to LIVVkit.

First, go to the LIVVkit github page and push the Fork button on the top right of the page. This will create a fork of LIVVkit in your profile page. Clone the fork, make your changes, merge them to development branch, and then submit a pull request to our public repository.

If you have any questions, concerns, requests, etc., open an issue in our public issues queue, and we will help you out.

Code Guidelines

Until LIVVkit 3.0 is released, all code should be written as python 2 and 3 compatible code – see http://python-future.org/compatible_idioms.html. Additionally, We generally follow PEP 8 guidelines as presented at pep8.org, with the exception of line lengths: lines have a soft limit of 100 characters and a hard limit of 120 characters when extra length improves readability. See of a very nice presentation of the PEP 8 style guide. A sample code snippet below highlights most of our coding conventions.

# coding=utf-8
# LICENSE...

"""
Description of module
"""

from __future__ import absolute_import, division, print_function, unicode_literals

import pymodule
import pymodule2

import livvmodule


class ClassName(object):
    """
    Class descriptions
    """


    def __init__(self):
        """ Constructor """
        self.var = "value"
        self.auto = "nalue"
        self.bagger = "salue"
        self.autocrummify = "dalue"


    @functionAnnotation
    def foo(self, bar, baz):
        """
        A description of foo.

        Args:
            bar: What is this.
            baz: What is this.
        Returns:
            a combo of bar and baz
        """
        # Some extra logic
        return bar + baz

Tips

  • Each source file containing functions that are called by the main livv.py script should have the license header. (There should be a script to fix when this is forgotten in util).
  • Global variables should be stored in the module util.variables. When adding new global variables list them in that module with some basic default value so that it is easy for others to see which variables may be used by outside modules.
  • When refering to system paths use the os.sep variable or os.path.join() instead of relying on whichever version of path separator your system uses.

Building the documentation

To build this documentation you will need to install some additional tools:

We recommend you use npm, a Javascript package manager, to install JSDoc and pip to install the Sphinx packages (sphinx itself can be installed via conda as well, but the others will still need pip).

To build the current version of the documentation website, simply run:

make html

from within the documentation directory.

When changes are made to the LIVVkit code base, the auto-generated files will need to be regenerated. First, you can clean out the old website and remove the auto-generated files by running:

make distclean

Warning

If you run this command you will need to regenerate all the auto-generated files! make clean will only remove the old website and leave the autogenerated files in place.

Then, auto-generate the documentation of LIVVkit’s python source code:

sphinx-apidoc -f -o source/ ../livvkit/

Now you’re ready to make the docs website again:

make html

Note

You can use the generate_docs.sh script to perform these steps.