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.
On Wed, 2019-04-10 at 14:42 +0200, Dmitry Tantsur wrote: 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?