Open Stack

Excerpts from Paul Belanger's message of 2016-12-24 15:23:35 -0500:
> 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.
> 

Using include works some places, but not others.

The include directive is a feature of Sphinx, not docutils. We use
Sphinx to convert reStructuredText to HTML for docs.o.o but github does
not use Sphinx when rendering individual reStructuredText files such as
CONTRIBUTING.rst or README.rst.

Since the point of having CONTRIBUTING.rst be a separate file is
to take advantage of the github.com integration to guide potential
contributors to the right forum for their contributions, we need
to ensure that those files render correctly by placing the content
directly into those files.  Then we can have project contributor
documentation use the include directive to avoid duplicating the
information elsewhere.

Doug