Open Stack

On Mon, Jan 2, 2017 at 11:03 AM, Doug Hellmann <doug at doughellmann.com>
wrote:

> 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, I think the include in Sphinx can be a raw txt file? Then we get the
best of both worlds - rendered on both docs.openstack.org and github.com.

I'll give that a shot with these patches as a proof of concept:

1. Change cookie-cutter file to CONTRIBUTING.txt
https://review.openstack.org/416109
2. Update openstack-manuals rendered docs with an included CONTRIBUTING.txt
https://review.openstack.org/416112

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.

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.

Anne


>
> Doug
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click <https://justwriteclick.com>
Subscribe to Docs|Code: docslikecode.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20170102/997aa755/attachment.html>