On 8/15/22 04:37, Vít Ondruch wrote:
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.
Another option is to have a system-wide package that the docs depend
on, via scripts loaded from file:// URLs. Not sure if that works.
If it does not, then bundling is the only option. In either case,
though, it should certainly be possible to fix the missing license
headers, and to ensure that the minified JS and CSS are built from
source during the build of the documentation generator.
--
Sincerely,
Demi Marie Obenour (she/her/hers)