Open Stack

On 2020-04-07 16:00:37 +0100 (+0100), Sean Mooney wrote:
[...]
> 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.
[...]

And I guess that's why it's coming back up again, but also with a
desire to do it for the HTML doc builds not just the PDFs.

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

Some projects put a thorough introduction in their README.rst and
don't want to have to duplicate it all in the Sphinx doc source tree
so just stick a ".. include:: ../../README.rst" line into
doc/source/index.rst or a similar document. It's typical for Debian
packages (though I haven't looked at Thomas's) to put the raw readme
somewhere like /usr/share/doc/foo/README.rst but also stick HTML
builds of the full documentation in a place like
/usr/share/doc/foo/html/ for ease of local indexing with tools like:

    https://manpages.debian.org/dhelp
    https://manpages.debian.org/dwww

The entire point of shipping these HTML builds in the compiled
packages is so that users have a local copy of documentation even if
they're somewhere with no working Internet access, and can even
build them from local copies of the source packages without working
Internet, therefore they need to not depend on external assets out
on the Internet and have to instead be buildable with only what's
packaged in the distro.
-- 
Jeremy Stanley
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20200407/6d1abd93/attachment.sig>