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 opening an issue on github and briefly describ 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

LIVVkit 3.0+ will be developed and tested on the three latest Python versions (3.6–3.8 for LIVVkit 3.0). 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. We use the Google Style for our Docstrings. A sample code snippet below highlights most of our coding conventions.

# coding=utf-8
# LICENSE...

"""
Description of module
"""

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

Building the documentation

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

• JSDoc

• sphinx

• sphinx-js

• sphinx-py3doc-enhanced-theme

We recommend you use npm, a Javascript package manager, to install JSDoc:

npm install -g jsdoc

and pip to install the development version of LIVVkit:

git clone git@github.com:LIVVkit/LIVVkit.git
cd LIVVkit
pip install -e .[develop]

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.