Dne 15. 08. 22 v 1:19 Demi Marie Obenour napsal(a):
On 8/11/22 10:23, Ben Beasley wrote:
> I don’t enjoy this topic at all, but I feel obligated to contribute some relevant
links.
>
> A previous discussion on the packaging mailing list[1] concluded that it doesn’t seem
possible to package HTML documentation generated by almost any system, including at least
Sphinx, Doxygen, and mkdocs, in a way that complies with guidelines around pre-compiled
and bundled JS, CSS, and fonts. See also [2], which started that discussion.
>
> There might be a conflict between this situation and certain language-specific
guidelines that prescribe packaging standardized documentation packages. For example,
[3].
>
> [1]
https://lists.fedoraproject.org/archives/list/packaging@lists.fedoraproje...
> [2]
https://bugzilla.redhat.com/show_bug.cgi?id=2006555
> [3]
https://bugzilla.redhat.com/show_bug.cgi?id=2097267
The best solution here is to patch Sphinx and Doxygen so they do not
produce nonredistributable output.
I am trying to wrap my head around this for RubyGems / RDoc for quite
some while, but it is unfortunately easier to say then do. Several issues:
1) If you separate the template from generated documentation, then the
documentation is not self contained anymore and transferable to
different location, which might break user expectations.
2) If you unbundle the template, then you should also unbundle e.g. the
font or JS from the template.
3) The system is not designed to support this scenario and I am not sure
if the change would be upstreamable.
4) Even if all the points above were solved, then the update of template
would need trigger regenerating all the documentation, to ensure the
documentation is not broken. You might argue, that the font change or
some JS library change or what not are just minor changes, but OTOH, you
don't want to ship broken documentation.
Vít