Sounds OK to me, though I personally don't know Git, so it'd have to be one of the developers doing it probably.

--

James Pulver

ZCA Member

LEPP Computer Group

Cornell University

I'll throw my two cents into each one of these topics. I don't have strong opinions on most of them, but I would like to see them brought to resolution.

Gaudy README.rst Template

It seems like the desire to create a template README.rst that screams out to be replaced is unanimous. I'm on board with that. Would anyone care to send me what they want to see? I'll get it into the ZenPackTemplate GitHub repository and into the mainline product so it gets automatically created for new ZenPacks when 4.2 is release.

Location of Screenshots

I prefer that the screenshots be kept in the code repository in the top-level directory. I haven't been particularly consistent in how I've done this with my ZenPacks to date. I second Jane's suggestion of creating a screenshots/ directory in the top-level.

As for where they go in the README.rst? I don't care, and I can see how some would prefer to highlight them at the beginning, intersperse them in context, or stick them at the bottom. I've tended towards the bottom myself because I like the information up front. I say leave it up to the author.

What to do about Eggs?

As Nick said, I'm in the process of building a system that will automatically build ZenPack eggs for all recent ZenPack versions anytime the repository is updated. I'm pretty excited about this because it's a pain in the neck to build all of the versions of ZenPack that people might need. You need a py2.6 version for Zenoss 3 and you'll need a py2.7 version for Zenoss 4.2 when it's released. If your ZenPack includes compiled code you'll need each one for i386 and x86_64 too.

For the immediate future we can use the GitHub "Downloads" area for packaged eggs. Once the auto-built archive is available, we can transition over to that as long as no one identifies a reason not to.

Automatically Building Documentation

dpetzel's idea of using Sphinx directly or readthedocs.org is a great one. I'm already using readthedocs.org for docs.zenosslabs.com and it has been a wonderful experience. It would be a minimal enhancement to build system to generate documentation in a variety of formats.

Regarding Automated Doc Building:

1) I would consider this a lose of current functionality (unless some sort of iframe approach is used)

2) No new Logon. Since we are talking about a read-only view of the DOCS, the source of the docs is GITHUB. At a high level a postcommit hook would simply fire off an automatic rebuild of the docs. This way each time a commit is performed DOCS are rebuilt. No Copying/Pasting from the required README.rst to JIVE.

3) I'd consider the conversion automatic (to an extent). If the development process is REQURING a README.rst, and the docs are auto-built. I think the conversion process might be as simple as updating current page to say "New Page is over here" and ensure the pack has valid RST file, or simply update the pages that have RST docs to use the proposed iFrame approach.

4) iFrames have the potential to bridge the Gap between old and new. I can't say I can exactly visualize how auto-build docs would look/feel in the iframe, but at  high level it feels like it could work. 

5) I believe I've seen docs from "Zenoss API" already so I think the JIVE API has already been figured out by Zenoss. I think the concerns around the API complexity can very likely be overcome.

I honestly feel this auto-doc building might be a premature discussion until the overall contribution process is hashed out (I should have started a seperate thread about it). I think THIS thread has deviated away from the original intention of making the process "less complex" and it only really applies to ZenPacks which are levarging GitHUB and RST. At this point thats a minority and potentially could stay that way for quite some time.