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 <akuri...@mirantis.com> > > Reply: OpenStack Development Mailing List (not for usage questions) > > <openstack-dev@lists.openstack.org> > > Date: December 21, 2016 at 10:13:09 > > To: OpenStack Development Mailing List (not for usage questions) > > <openstack-dev@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 __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev