<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Jan 2, 2017 at 11:03 AM, Doug Hellmann <span dir="ltr"><<a href="mailto:doug@doughellmann.com" target="_blank">doug@doughellmann.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Excerpts from Paul Belanger's message of 2016-12-24 15:23:35 -0500:<br>
<div><div class="gmail-m_6826374699169730664h5">> On Wed, Dec 21, 2016 at 10:17:42AM -0600, Ian Cordasco wrote:<br>
> > -----Original Message-----<br>
> > From: Andrey Kurilin <<a href="mailto:akurilin@mirantis.com" target="_blank">akurilin@mirantis.com</a>><br>
> > Reply: OpenStack Development Mailing List (not for usage questions) <<a href="mailto:openstack-dev@lists.openstack.org" target="_blank">openstack-dev@lists.openstack<wbr>.org</a>><br>
> > Date: December 21, 2016 at 10:13:09<br>
> > To: OpenStack Development Mailing List (not for usage questions) <<a href="mailto:openstack-dev@lists.openstack.org" target="_blank">openstack-dev@lists.openstack<wbr>.org</a>><br>
> > Subject:  Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects<br>
> ><br>
> > > On Wed, Dec 21, 2016 at 5:46 PM, Andreas Jaeger wrote:<br>
> > ><br>
> > > > On 2016-12-21 16:22, Ian Cordasco wrote:<br>
> > > > > [...]<br>
> > > > > That said, I think there are two better places for this information<br>
> > > > > that are already standards in OpenStack:<br>
> > > > ><br>
> > > > > * README.rst<br>
> > > > > * HACKING.rst<br>
> > > > ><br>
> > > > > Most projects include links to the contributing documentation in at<br>
> > > > > least one of these files. I think the effort here is to standardize,<br>
> > > > > albeit in a brand new file, and that's admirable.<br>
> > > ><br>
> > > > If that's the goal - to standardize - then I would expect that we move<br>
> > > > all the documentation out of those files in one place.<br>
> > > ><br>
> > > > Right now, the changes duplicate information that exists - and the new<br>
> > > > information is often wrong. It points to place that do not exist or<br>
> > > > where better places exist. ;(<br>
> > > ><br>
> > ><br>
> > > Duplication can be reduced by using `.. include:: ` directive.<br>
> ><br>
> > That does not render anywhere except our documentation (via Sphinx). Git{Hub,Lab} don't render the include directive at all.<br>
> ><br>
> > So, no, that's not an option.<br>
> ><br>
> No, this is a valid option. We do it today with various documentation.<br>
><br>
> They will however render to docs.o.o, which we consider source of truth. The<br>
> topic of rendering RST files to github has come up a few times, but each time<br>
> comes back to the fact we simply mirror to github.<br>
><br>
> It is possible to have <a href="http://git.openstack.org" rel="noreferrer" target="_blank">git.openstack.org</a> render RST too, but we've opted to do<br>
> it with <a href="http://docs.openstack.org" rel="noreferrer" target="_blank">docs.openstack.org</a>.<br>
><br>
<br>
</div></div>Using include works some places, but not others.<br>
<br>
The include directive is a feature of Sphinx, not docutils. We use<br>
Sphinx to convert reStructuredText to HTML for docs.o.o but github does<br>
not use Sphinx when rendering individual reStructuredText files such as<br>
CONTRIBUTING.rst or README.rst.<br>
<br>
Since the point of having CONTRIBUTING.rst be a separate file is<br>
to take advantage of the <a href="http://github.com" rel="noreferrer" target="_blank">github.com</a> integration to guide potential<br>
contributors to the right forum for their contributions, we need<br>
to ensure that those files render correctly by placing the content<br>
directly into those files.  Then we can have project contributor<br>
documentation use the include directive to avoid duplicating the<br>
information elsewhere.<br></blockquote><div><br></div><div>Doug, I think the include in Sphinx can be a raw txt file? Then we get the best of both worlds - rendered on both <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a> and <a href="http://github.com" target="_blank">github.com</a>.</div><div><br></div><div>I'll give that a shot with these patches as a proof of concept:</div><div><br></div><div>1. Change cookie-cutter file to CONTRIBUTING.txt <a href="https://review.openstack.org/416109">https://review.openstack.org/416109</a><br></div><div>2. Update openstack-manuals rendered docs with an included CONTRIBUTING.txt <a href="https://review.openstack.org/416112">https://review.openstack.org/416112</a></div><div><br></div><div>We won't really know the GitHub UI rendering of the include until merged, but I've tested in other repos and changing the file extension to .txt gives a link to that file.</div><div><br></div><div>Thoughts? Please comment on the reviews or here. I can work on it if we think it's worthwhile to standardize upon, and/or collaborate with the original contributor who wanted to standardize. I do believe the GitHub experience is worthy of attention, similar in my mind to the recent badges work.</div><div><br></div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<span class="gmail-m_6826374699169730664HOEnZb"><font color="#888888"><br>
Doug<br>
</font></span><div class="gmail-m_6826374699169730664HOEnZb"><div class="gmail-m_6826374699169730664h5"><br>
______________________________<wbr>______________________________<wbr>______________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.op<wbr>enstack.org?subject:unsubscrib<wbr>e</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi<wbr>-bin/mailman/listinfo/openstac<wbr>k-dev</a><br>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail-m_6826374699169730664gmail_signature"><div dir="ltr"><div><div dir="ltr"><div dir="ltr"><div dir="ltr"><div><br></div><div>Read my blog: <a href="https://justwriteclick.com" target="_blank">justwrite.click</a></div><div>Subscribe to Docs|Code: <a href="http://docslikecode.com" target="_blank">docslikecode.com</a> </div></div></div></div></div></div></div>
</div></div>