[all] Please remove all external resources from docs

Sean Mooney smooney at redhat.com
Tue Apr 7 15:00:37 UTC 2020


On Tue, 2020-04-07 at 13:52 +0000, Jeremy Stanley wrote:
> On 2020-04-07 10:47:41 +0100 (+0100), Graham Hayes wrote:
> [...]
> > It *might* make sense - the info it shows is time dependent, so if
> > a project was asserting follows-stable-policy in pike, showing
> > that is not necessarily _wrong_ ... Same as if a project was moved
> > out of OpenStack in Havana, the docs could show the openstack
> > project badge until then.
> 
> [...]
> 
> Fair, if folks prefer that, then the docs build jobs could require
> the governance repo to obtain the requisite metadata and incorporate
> the Sphinx extension which generates these SVG images.
for what its worth im not sure why this thread was suddenly revied after 6 months
or maybe i was ignoring it but we discussed this as part of the pdf docs item back
in denver and for the pdf docs we did want to convert the badges into svgs and enbed
them but i dont know if that was ever done because it too a lot of time to get the
initally docs builing correctly so i think the task to be able to embed rather then 
link to the badges may have fallen by the way side.
>  That still
> might be unworkably complicated for downstream packaging in distros
> however, since we don't version and release the contents of the
> governance repo, so would likely need to start doing that (at least
> for the projects.yaml and Sphinx extension) and declare it as a
> min-versioned docs build dependency. Seems like a lot of work
> compared to just stripping them out. My point was that these badges
> are mostly only relevant to folks browsing README files in a source
> code hosting platform, but when the README is embedded into a
> compiled Sphinx document they seem really out of place and are
> probably best omitted.
a simple anser would also be to not ship the readme in the docs or do its
as plain text. i presonally prefer to read the rst before they are renderd
anyway so if i was looking for the docs in a a disto package i would be hoping
to find the rst files not the html docs.




More information about the openstack-discuss mailing list