Skip to content

Contributing to Documentation

If you're looking to help document Policy Sentry, your first step is to get set up with Mkdocs, our documentation tool. First you will want to make sure you have a few things on your local system:

  • python-dev (if you're on OS X, you already have this)
  • pip

Once you've got all that, the rest is simple:

# If you have a fork, you'll want to clone it instead
git clone git@github.com:salesforce/policy_sentry.git

# Set up the virtual environment
python3 -m venv ./venv && source venv/bin/activate
pip3 install -r requirements.txt
pip3 install -r requirements-dev.txt

# Create the HTML files
invoke docs.build-docs
invoke docs.serve-docs

# The above will open the built documentation in your browser

Docstrings

The comments under each Python Module are Docstrings. We use those to generate our documentation. See more information here.

Use the Google style for Docstrings, as shown here

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True