openstack team mailing list archive

[Ewan Mellor <Ewan.Mellor@xxxxxxxxxxxxx>]

.rst is ReStructured Text.  It's the markup language being used.

Cheers,

Ewan.

> -----Original Message-----
> From: openstack-bounces+ewan.mellor=citrix.com@xxxxxxxxxxxxxxxxxxx
> [mailto:openstack-bounces+ewan.mellor=citrix.com@xxxxxxxxxxxxxxxxxxx]
> On Behalf Of Andrew Bogott
> Sent: Thursday, March 22, 2012 9:22 AM
> To: openstack@xxxxxxxxxxxxxxxxxxx
> Subject: [Openstack] Being pedantic about pedanticism: HACKING
> styleguide
> 
>      Just now I set out to merge a recent style guide change from
> python-novaclient into the hacking docs of other OpenStack projects.
> My patch didn't apply, though, because each project has subtly
> diverging HACKING files.
> 
>      Rather than contribute to this divergence, I've now read and
> compared the style guides from Nova, Glance, Keystone, python-
> keystoneclient, and python-novaclient.  From these diffs I've created a
> file (attached) that encompasses the total of all guidelines from all
> projects.  Remarkably, this merge produced only minor disagreements,
> described below under the heading FLAMEBAIT.
> 
>      I propose that this unified style guide be copied into each of the
> above projects, with a mandate to maintain consistency henceforth.  Any
> objections?
> 
> -Andrew
> 
> 
> FLAMEBAIT (docstring format):
> 
> The only explicit contradiction I came across is regarding docstring
> formatting.  Glance says this:
> 
> **DO NOT** leave an extra newline before the closing triple-double-
> quote.
> 
> Nova, this:
> 
>    A docstring ends with an empty line before the closing quotations.
> 
> I propose that we just pick one or the other, or remove both
> prescriptions.
> 
> FLAMEBAIT (filename):
> 
> Some projects have a HACKING file, and some have a HACKING.rst file.
> Doesn't .rst generally indicate a REST API definition?  I propose that
> the file be called HACKING.