Zenpackers Documentation

Description

Zenpackers is a documentation source for advanced ZP developers that goes beyond what is documented in the existing online documents. Its not meant to be a permanent storage but rather a staging ground for ZP development ideas that can be later moved to permanent documentation. The Sphinx technology we use is very easy to write in and has an easy build target.

Motivation

This documentation is intended to augment the existing documentation to assist ZenPack developers. It is the hope of this project to reduce the amount of repeated support and questions related to ZP dev, facilitate development progress.

This project is located at https://github.com/zenoss/ZenPackers

Consider writing and transcribe your juicy morsels of knowledge into new documentation. We’d like to venture that each of us can easily put in 30 minutes of documentation per iteration, to this end.

For veterans of ZP development, this can help reduce the amount of repeating of answers that could easily have a well documented solution. For newbies, it could help you to cement your ideas together and provide you with a good documentation that can remind you 3 weeks later when you may have forgotten what you have done.

How to Contribute to Zenpackers: Sphinx-Doc

We use Sphinx to write these documents. Its easy to install and use in Linux and OSX. Sphinx uses Restructured Text format, which can be found here:

We cover several OS setup scenarios below.

Installing Sphinx-Doc

General documentation is at http://sphinx-doc.org/latest/install.html

In Debian/Ubuntu, you need (at minimum) these packages:

apt-get install python-sphinx make

In Centos or Redhat:

yum install python-sphinx.noarch make

In MacOSX:

brew install sphinx

For Windows, read the installation docs:

Downloading the ZenPackers Source from Git

Download the source here:

git clone git@github.com:zenoss/ZenPackers.git
cd ZenPackers

Installing and using Git-Flow to create a feature

In that same document we outline how to:

  • Initialize Git flow on your repo
  • Create a feature branch bases on develop

For example, from in the ZenPackers repo:

git flow init
git flow feature start JoesGarage

Now you can start making changes to the repo.

Building HTML or Other Targets for testing

Once you have made changes to the RST files, you can test it by generating HTML. In order to build the HTML you simply do this:

cd Zenpackers
make html ; cp -a build/html /tmp/

You can view the HTML on the local system at /tmp/build/html. If you work remotely, you’ll have to copy those files to your local system using the file tranfer tool of your choice.

Submitting a Pull Request

Once you finish your changes, you need to commit and push up your feature changes as such:

git commit -am "Adding/Modifying a file for JoesGarage Zenpack"
git push

Now go to the github repo page, and make a pull request:

Review a Pull Request

Once your pull request is in, someone can review it and merge it into the develop branch, using the GitHub web interface.

This allows others to review and make change recommendations. You may have to make changes, commit, and push changes as above. You don’t have to make a new pull request.

Important Security Information

Make sure that you sanitize any document that may have proprietary or security related information. At minimum, this includes:

  • IP addresses
  • network Numbers
  • usernames
  • passwords
  • personal information of any type