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=2097267The 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
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
_______________________________________________ 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
