Hi Salman, On Tue, Sep 24, 2019 at 12:19:54AM +0200, Salman Mohammadi wrote: > Package: elpa-elpy > Version: 1.31.0-1 > Severity: wishlist > > Dear Nicholas, > > It would be nice if you create the package `elpy-doc` alongside > elpa-elpy to manage html docs separately. > > If you want, I can also offer my help, in form of an MR, to reduce the time > you need to > invest on this matter >
Thanks for the offer, I appreciate your enthusiasm! :-)
In this case I had previously decided to keep the html docs part of
the elpa-elpy package and not break them out, because:
While this is a hybrid elisp+python package, it primarily follows Emacs
packaging conventions. eg: originally it shipped documentation in info
and manpage formats, but not in html. Adding html was a concession
for Python developers' expectations (this is a Python IDE after all!),
but I want the info page to remain part of the main package.
Debian Policy §12.3 states
If package is a build tool, development tool, command-line tool,
or library development package, package (or package-dev in the
case of a library development package) already provides
documentation in man, info, or plain text format, and package-doc
provides HTML or other formats, package should declare at most a
Suggests on package-doc. Otherwise, package should declare at most
a Recommends on package-doc.
That means that elpa-elpy would only be able to "declare at most a
Suggests on" proposed elpy-doc package, meaning it wouldn't be
installed by default with elpa-elpy.
The HTML docs are only 476K (a little over half the size of Parso's).
I'm not convinced that this fulfills "If a package comes with large
amounts of documentation that many users of the package will not
require" (Policy §12.3) recommendation for a separate doc package, and
also because IMHO Elpy is near impossible to use effectively without
its documentation; A poor experience with other IDEs' documentation is
another reason I've chosen a politic of "maximum accessibility to
documentation" for this package. I also suppose that users will have
already installed some other Python documentation and reference
material, so am not counting the disk space for sphinx and libjs (and
rtd theme, thanks again for the MR) deps.
In a nutshell, I chose the current method because I believe it
provides the greatest good. If enough people disagree, the options
that are conformant to policy seem to be:
1. Create elpy-doc and move the man and info pages to this package,
and Recommend it. Users who install with --no-install-recommends
may complain basic necessary documentation is not included, or
may just give up.
2. Move HTML docs to elpy-doc, and declare it as a Suggests. Users
may complain that their preferred format for documentation is not
installed by default. There was already a bug filed to this
affect.
Let's keep this bug open for a few years, in case other people
disagree.
Kind regards,
Nicholas
signature.asc
Description: PGP signature
