Open Stack

On Wed, Dec 21, 2016 at 10:17:42AM -0600, Ian Cordasco wrote:
> -----Original Message-----
> From: Andrey Kurilin <akurilin at mirantis.com>
> Reply: OpenStack Development Mailing List (not for usage questions) <openstack-dev at lists.openstack.org>
> Date: December 21, 2016 at 10:13:09
> To: OpenStack Development Mailing List (not for usage questions) <openstack-dev at lists.openstack.org>
> Subject:  Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects
> 
> > On Wed, Dec 21, 2016 at 5:46 PM, Andreas Jaeger wrote:
> >  
> > > On 2016-12-21 16:22, Ian Cordasco wrote:
> > > > [...]
> > > > That said, I think there are two better places for this information
> > > > that are already standards in OpenStack:
> > > >
> > > > * README.rst
> > > > * HACKING.rst
> > > >
> > > > Most projects include links to the contributing documentation in at
> > > > least one of these files. I think the effort here is to standardize,
> > > > albeit in a brand new file, and that's admirable.
> > >
> > > If that's the goal - to standardize - then I would expect that we move
> > > all the documentation out of those files in one place.
> > >
> > > Right now, the changes duplicate information that exists - and the new
> > > information is often wrong. It points to place that do not exist or
> > > where better places exist. ;(
> > >
> >  
> > Duplication can be reduced by using `.. include:: ` directive.
> 
> That does not render anywhere except our documentation (via Sphinx). Git{Hub,Lab} don't render the include directive at all.
> 
> So, no, that's not an option.
> 
No, this is a valid option. We do it today with various documentation.

They will however render to docs.o.o, which we consider source of truth. The
topic of rendering RST files to github has come up a few times, but each time
comes back to the fact we simply mirror to github.

It is possible to have git.openstack.org render RST too, but we've opted to do
it with docs.openstack.org.