Open Stack

On Tue, 2019-04-09 at 18:46 +0200, Dmitry Tantsur wrote:
> On 4/8/19 8:13 PM, Sean McGinnis wrote:
> > > > > 
> > > > > 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.
> > > 
> > 
> > What is in the README that is needed in the documentation? For me, those have
> > always been entirely different audiences and therefore different content.
> 
> I don't think it's any different. Both README and the index page serve as an 
> introduction to the project. The same people will land at one of them, depending 
> if they come from github/gitea or from docs.o.o
you assume that devs read docs.o.o
i personally much prefer reading the rst then the renderd html content
so i think they do have slight different auidence in that respect even if they have
the same contet.

i could happily live in a world wehre docs.o.o was not a thing but if the RSTs ever
got to a point where they were not readable without sphinx due to tomany uses
of include then that woudl be an issue for me.
> 
> > 
> > Maybe it just needs a different perspective for these project from how they've
> > used them so far?
> > 
> 
>