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