Open Stack

On Mon, 2019-04-08 at 19:40 +0200, Dmitry Tantsur wrote:
> On 4/8/19 4:07 PM, Monty Taylor wrote:
> > 
> > On 4/8/19 11:33 AM, Sean McGinnis wrote:
> > > > Perhaps we can find a good pattern for
> > > > having a README with badge types of things that includes actual content from
> > > > the docs?
> > > 
> > > One concern to keep in mind if you start looking down this path is that most
> > > projects use their README by default as their package long-description. That
> > > means that when uploading a package to PyPi, it will use the content of the
> > > README as the description that is shown for that package.
> > > 
> > > The rendering on PyPi, and the validation that they do that will reject the
> > > package upload if it has README syntax errors, is not aware of any Sphinx
> > > extensions we use in our normal docs, so pulling in other documentation into
> > > the README could potentially cause release issues.
> > 
> > Good point. Maybe we should just stop including README content in sphinx docs, 
> > and not do anything additional that's more complex?
> > 
> 
> Honestly, this means copy-paste and that one of the copies will probably get 
> outdated.

You could do a partial include.

  .. include:: ../../README.rst
     :start-line: N

though I, like Sean, would question the wisdom of this since the README
does have a different focus group

Stephen