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@xxxxxxxxxxxxxxxxxxxxxxx/thread/LLUAURXZVADATHK65HBPPBHKF4EM4UC3/ >>> [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) _______________________________________________ devel mailing list -- devel@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to devel-leave@xxxxxxxxxxxxxxxxxxxxxxx Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/devel@xxxxxxxxxxxxxxxxxxxxxxx Do not reply to spam, report it: https://pagure.io/fedora-infrastructure/new_issue
