Open Stack

On Wed, 2019-04-10 at 14:42 +0200, Dmitry Tantsur wrote:
> On 4/10/19 2:26 PM, Sean Mooney wrote:
> > 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
> 
> Well, I personally do read them all the time..
> 
> > 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 think the audience will see whatever the search engine will lead them to. 
> https://duckduckgo.com/?q=openstack+nova gives me 1. docs.o.o, 2. wiki, 3. 
> github. Chances are very high I would check the docs rather then the source code 
> first.
perhaps but my search engine for doc is 
a.) grep ~/repo/openstack/nova
b.) github.com/<org>/<project>
c.) codesearch.openstack.org

that is not ture of all the docs i use
https://developer.openstack.org/api-ref/compute/
and the ohter api refs i almost exclcively view online
and i use https://docs.openstack.org/nova/latest/configuration/config.html
a reasonable amount but even then if will often check the source code.
ince we centralised all the config opts and move the documention into the code
https://github.com/openstack/nova/tree/master/nova/conf is jsut as fast

im not saying docs.o.o is not useful i do use it but the only source of docs i have
never used in distor or pypi packages.

anyway this is a little off topic the privacy concerns are obviosly vlaid in some respect
and i think we can like fine a path forward that suties everyone.

personlay i would not include any content in from the docs in the readme and instead just provide links
to the relevent sections.

for example i think the nova readme is is good as it is https://github.com/openstack/nova/blob/master/README.rst
but i also get that you might not want to embed non local images.

i persoall woudl expect most people to read the readme either via gitub/pypi
or with nano/vim/emac/<beloved editor of choice> localy. i would not expect peopel to read a rendered
html form of the readme outside of github/pypi/gitea

> 
> > 
> > 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?
> > > > 
> > > 
> > > 
> 
>