https://bugzilla.redhat.com/show_bug.cgi?id=2369464 --- Comment #6 from Ben Beasley <code@xxxxxxxxxxxxxxxxxx> --- (In reply to Benson Muite from comment #5) > > For Sphinx, it is possible to add macros to make this easier, as new > macros are being added, it is a good time to consider this and make > people aware it is available. > > […] > > Docbook does not introduce extra fonts, js or CSS and there is a viewer > already packaged. There is some expertise in Fedora for docbook format: > https://packages.fedoraproject.org/pkgs/publican/ Indeed, Docbook looks like it has potential for this kind of documentation, and I am interested in the idea of a better way to deal with Sphinx-generated documentation in general. I just don’t see a reason for this particular package to be in the vanguard of that. I’m not saying it’s a bad format. It does seem to avoid a lot of the pitfalls of some other formats, which is kind of exciting, although I haven’t reviewed the result in a viewer to see how well it actually turned out. I’m just not sure that introducing Sphinx-generated docbook files to a handful of individual packages does much good except as a proof of concept. It seems like, for the effort of building this kind of documentation to be worthwhile, we need at least a partial consensus that (1) “we collectively value packaging generated Python library API documentation,” (2) “Sphinx-generated docbook output is normally of good quality in practice,” and (3) “this is how we would like to present Python library API documentation by default,“ especially for a format that many people, even developers, aren’t used to dealing with. If that consensus existed, I could quickly add docbook documentation to *dozens* of packages, even only considering those for which I am primary maintainer, but I am not yet confident that adding and maintaining this format is a good use of time and other resources. -- You are receiving this mail because: You are always notified about changes to this product and component You are on the CC list for the bug. https://bugzilla.redhat.com/show_bug.cgi?id=2369464 Report this comment as SPAM: https://bugzilla.redhat.com/enter_bug.cgi?product=Bugzilla&format=report-spam&short_desc=Report%20of%20Bug%202369464%23c6 -- _______________________________________________ package-review mailing list -- package-review@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to package-review-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/package-review@xxxxxxxxxxxxxxxxxxxxxxx Do not reply to spam, report it: https://pagure.io/fedora-infrastructure/new_issue
