[all] Removing privacy breaches in doc
Hi, In may docs, I can see stuff like this, especially in README.rst: .. image:: http://governance.openstack.org/badges/something.svg :target: http://governance.openstack.org/reference/tags/index.html I'd like to let everyone know that, from a package maintainer perspective, and considering that we do package your Sphinx doc in distros, this is an annoyance. Indeed, I do feel like I must patch it out and remove the external source. The reason is, as a Debian user, I do not expect my browser to do external queries to a website when I'm browsing a local documentation. This one is on openstack.org, it's mildly ok-ish, though, I'm removing the image still. There's other more annoying stuff (think: travis, github, and other spies which we don't control). So, it'd be nice if these images with external resources were completely avoided in OpenStack docs. Either by simply not putting such useless image, replacing it by text only, or by embedding the image itself in the doc (or in openstackdocstheme? I suspect that's not what people want, they want it to be displayed in github... so embedding would be the only solution). Cheers, Thomas Goirand (zigo)
Hi,
In may docs, I can see stuff like this, especially in README.rst:
.. image:: http://governance.openstack.org/badges/something.svg :target: http://governance.openstack.org/reference/tags/index.html
I'd like to let everyone know that, from a package maintainer perspective, and considering that we do package your Sphinx doc in distros, this is an annoyance. Indeed, I do feel like I must patch it out and remove the external source.
The reason is, as a Debian user, I do not expect my browser to do external queries to a website when I'm browsing a local documentation. This one is on openstack.org, it's mildly ok-ish, though, I'm removing the image still. There's other more annoying stuff (think: travis, github, and other spies which we don't control).
So, it'd be nice if these images with external resources were completely avoided in OpenStack docs. Either by simply not putting such useless image, replacing it by text only, or by embedding the image itself in the doc (or in openstackdocstheme? I suspect that's not what people want, they want it to be displayed in github... so embedding would be the only solution). am we could do this but they do not exist to spy on people.
On Sat, 2019-04-06 at 00:06 +0200, Thomas Goirand wrote: the are there to let people know that a project is maintained and follows different aspect of the governace policys. such as is it vulnerablity managed or suppors-upgrades. i undersand the concern but the reason we follow the current linking approch instead of embeding is allow them to be centrally managed in a singel repo. perhaps we can figure out how to automtically staticaly embed them some how so that when sphinx build executes it embdes a local copy in the html? i dont think these image are useless as they do provide relevent info to users of the respecitve project although ill admit i had assumed these tags actully were not a singel image but were added one by one.
Cheers,
Thomas Goirand (zigo)
On 4/6/19 12:35 AM, Sean Mooney wrote:
perhaps we can figure out how to automtically staticaly embed them some how so that when sphinx build executes it embdes a local copy in the html?
That'd be nice indeed.
i dont think these image are useless as they do provide relevent info to users of the respecitve project
I agree, and that's also why it bothers me each time I patch them out. Cheers, Thomas Goirand (zigo) P.S: No need to Cc me, I'm subscribed! :)
On 2019-04-06 01:14:45 +0200 (+0200), Thomas Goirand wrote:
On 4/6/19 12:35 AM, Sean Mooney wrote:
perhaps we can figure out how to automtically staticaly embed them some how so that when sphinx build executes it embdes a local copy in the html?
That'd be nice indeed. [...]
Well, except then they'd presumably be downloading those images during the build process, which is similarly problematic, unless the images can also be packaged in Debian and used as a build-dep. -- Jeremy Stanley
On 4/6/19 3:12 PM, Jeremy Stanley wrote:
On 2019-04-06 01:14:45 +0200 (+0200), Thomas Goirand wrote:
On 4/6/19 12:35 AM, Sean Mooney wrote:
perhaps we can figure out how to automtically staticaly embed them some how so that when sphinx build executes it embdes a local copy in the html?
That'd be nice indeed. [...]
Well, except then they'd presumably be downloading those images during the build process, which is similarly problematic, unless the images can also be packaged in Debian and used as a build-dep.
Why not having them in openstackdocstheme (or similar)? Cheers, Thomas Goirand (zigo)
On 2019-04-07 00:01:58 +0200 (+0200), Thomas Goirand wrote: [...]
Why not having them in openstackdocstheme (or similar)?
Right now the images are compiled based on data stored in the openstack/governance repository, so it would probably be simplest if they were packaged separately (otherwise that data would still need to be pulled into another codebase somehow). -- Jeremy Stanley
Jeremy Stanley <fungi@yuggoth.org> writes:
On 2019-04-07 00:01:58 +0200 (+0200), Thomas Goirand wrote: [...]
Why not having them in openstackdocstheme (or similar)?
Right now the images are compiled based on data stored in the openstack/governance repository, so it would probably be simplest if they were packaged separately (otherwise that data would still need to be pulled into another codebase somehow). -- Jeremy Stanley
We release the governance repo as a library [1] so that some of the release tools can use the API to consume the data. We could bundle the images into that library and have the theme use it. BUT, that would make the images depend on the point-in-time of that governance library release, and the tags do tend to change. It would be better to, as Monty suggested, restructure the documentation so that dynamic components aren't needed for the regular docs. One way we could enforce that is by removing the settings that ignore references to "nonlocal images", which we have in the sphinx config files for a few projects [2]. This would ensure that only images checked into git (or built from other artifacts that are) could be included in the docs we build through sphinx. [1] https://pypi.org/project/openstack-governance/ [2] http://codesearch.openstack.org/?q=image.nonlocal_uri&i=nope&files=&repos= -- Doug
On 4/5/19 10:06 PM, Thomas Goirand wrote:
Hi,
In may docs, I can see stuff like this, especially in README.rst:
.. image:: http://governance.openstack.org/badges/something.svg :target: http://governance.openstack.org/reference/tags/index.html
I'd like to let everyone know that, from a package maintainer perspective, and considering that we do package your Sphinx doc in distros, this is an annoyance. Indeed, I do feel like I must patch it out and remove the external source.
The reason is, as a Debian user, I do not expect my browser to do external queries to a website when I'm browsing a local documentation. This one is on openstack.org, it's mildly ok-ish, though, I'm removing the image still. There's other more annoying stuff (think: travis, github, and other spies which we don't control).
FWIW - it would be exceptually strange for OpenStack projects to include travis or github badges in documentation since we don't use those services. Which is to say - for things that aren't governance badges, I'd be curious to learn about and erradicate such things.
So, it'd be nice if these images with external resources were completely avoided in OpenStack docs. Either by simply not putting such useless image, replacing it by text only, or by embedding the image itself in the doc (or in openstackdocstheme? I suspect that's not what people want, they want it to be displayed in github... so embedding would be the only solution).
opendev.org will now show these too - so I believe they are 'desirable' in README files. Perhaps instead of trying to get rid of them or make things extra harder for folks - we could consider ending the practice of doing a sphinx include of the README.rst content in the docs. Perhaps we can find a good pattern for having a README with badge types of things that includes actual content from the docs? I'm not sure how well include paths work in the opendev RST renderer - but might be worth exploring. Then we could have clean docs and badged READMEs. Or?
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. Sean
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?
On 2019-04-08 14:07:01 +0000 (+0000), Monty Taylor wrote: [...]
Good point. Maybe we should just stop including README content in sphinx docs, and not do anything additional that's more complex?
I must admit, I find the simplicity of this solution extremely compelling. -- Jeremy Stanley
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?
That would be my preference. :)
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.
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. Maybe it just needs a different perspective for these project from how they've used them so far?
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
Maybe it just needs a different perspective for these project from how they've used them so far?
On 2019-04-09 18:46:59 +0200 (+0200), Dmitry Tantsur wrote: [...]
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 [...]
We typically embed them in Python package descriptions too, so it's a question of whether there's significant overlap between the people starting from source browsers and PyPI, or starting from published documentation. -- Jeremy Stanley
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
On Tue, 2019-04-09 at 18:46 +0200, Dmitry Tantsur wrote: 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?
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.
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?
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?
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
participants (8)
-
Dmitry Tantsur
-
Doug Hellmann
-
Jeremy Stanley
-
Monty Taylor
-
Sean McGinnis
-
Sean Mooney
-
Stephen Finucane
-
Thomas Goirand