Re: nodoc solution HOWTO -- Avoid building Sphinx documentation on request (was: Bug#905750: RFS: elpy/1.23.0-1)
Hi Niels, On Wed, Sep 05, 2018 at 05:45:00AM +, Niels Thykier wrote: [...] > Rather, I think there is a typo in changes. > > > --- > > debian/changelog | 6 ++ > > debian/control | 4 ++-- > > debian/rules | 8 +++- > > 3 files changed, 15 insertions(+), 3 deletions(-) > > > > [...] > > diff --git a/debian/rules b/debian/rules > > index a9d70b4..bd4c218 100755 > > --- a/debian/rules > > +++ b/debian/rules > > @@ -11,7 +11,13 @@ export LC_ALL > > # docs are not generated without this override > > override_dh_auto_build: > > dh_auto_build > > - PYTHONPATH=. sphinx-build -N -bman docs/ build/man # Manpage generator > > +# support the nodoc build profile > > +ifneq ($(filter nodocs,$(DEB_BUILD_PROFILES)),) >^^ > > nodocs != nodoc Thank you for pointing this out, you're right, my mistake :-) When I fixed it, I also discovered that dh_sphinxdoc doesn't detect that nodoc is active, so worked around it and filed #908078. For now, here is the working solution (including dh_sphinxdoc workaround) sans typo. --- a/debian/control +++ b/debian/control @@ -27,8 +27,8 @@ Build-Depends: debhelper (>= 11~) , python3-mock , python3-nose , python3-pip - , python3-sphinx - , texinfo + , python3-sphinx + , texinfo Standards-Version: 4.2.1 Vcs-Browser: https://salsa.debian.org/emacsen-team/elpy Vcs-Git: https://salsa.debian.org/emacsen-team/elpy.git diff --git a/debian/rules b/debian/rules index a9d70b4..47f597b 100755 --- a/debian/rules +++ b/debian/rules @@ -6,12 +6,23 @@ LC_ALL := C.UTF-8 export LC_ALL %: +ifneq ($(filter nodoc,$(DEB_BUILD_PROFILES)),) + echo -e "\nnodoc profile enabled, building without sphinxdoc..\n" + dh $@ --with elpa,python3 --buildsystem=pybuild +else dh $@ --with elpa,python3,sphinxdoc --buildsystem=pybuild +endif # docs are not generated without this override override_dh_auto_build: dh_auto_build - PYTHONPATH=. sphinx-build -N -bman docs/ build/man # Manpage generator +# support the nodoc build profile +ifneq ($(filter nodoc,$(DEB_BUILD_PROFILES)),) + echo -e "\nnodoc build profile enabled, therefor not building docs.\n" +else + PYTHONPATH=. sphinx-build -N -bman docs/ build/man PYTHONPATH=. sphinx-build -N -btexinfo docs/ build/info makeinfo --no-split build/info/Elpy.texi -o build/info/elpy.info cat NEWS.rst debian/local-var-snippet > build/NEWS +endif Sincerely, Nicholas signature.asc Description: PGP signature
Re: nodoc solution HOWTO -- Avoid building Sphinx documentation on request (was: Bug#905750: RFS: elpy/1.23.0-1)
Nicholas D Steeves: > Hi Ben and readers of debian-mentors, > > Solution at bottom. > > [...] > > "export DEB_BUILD_PROFILES=nodoc ; gbp buildpackage" does not work, > although I expect "DEB_BUILD_PROFILES=nodoc ; export > DEB_BUILD_PROFILES ; gbp buildpackage" should. > Rather, I think there is a typo in changes. > --- > debian/changelog | 6 ++ > debian/control | 4 ++-- > debian/rules | 8 +++- > 3 files changed, 15 insertions(+), 3 deletions(-) > > [...] > diff --git a/debian/rules b/debian/rules > index a9d70b4..bd4c218 100755 > --- a/debian/rules > +++ b/debian/rules > @@ -11,7 +11,13 @@ export LC_ALL > # docs are not generated without this override > override_dh_auto_build: > dh_auto_build > - PYTHONPATH=. sphinx-build -N -bman docs/ build/man # Manpage generator > +# support the nodoc build profile > +ifneq ($(filter nodocs,$(DEB_BUILD_PROFILES)),) ^^ nodocs != nodoc > + echo -e "\nnodoc build profile enabled, therefor not building docs.\n" > +else > + PYTHONPATH=. sphinx-build -N -bman docs/ build/man > PYTHONPATH=. sphinx-build -N -btexinfo docs/ build/info > makeinfo --no-split build/info/Elpy.texi -o build/info/elpy.info > cat NEWS.rst debian/local-var-snippet > build/NEWS > +endif > + > Thanks, ~Niels
Re: nodoc solution HOWTO -- Avoid building Sphinx documentation on request (was: Bug#905750: RFS: elpy/1.23.0-1)
Hi Ben and readers of debian-mentors, Solution at bottom. On Sat, Sep 01, 2018 at 08:26:07PM -0400, Nicholas D Steeves wrote: > On Fri, Aug 10, 2018 at 06:02:14AM +1000, Ben Finney wrote: > > Chris Lamb writes: > > > > > * You should probably avoid building the documentation too if the > > >nodocs build profile is enabled. > > > > For packages from PyPI which have documentation detectable by > > ‘dh_sphinxdoc’, does this (avoid building the documentation if the > > “nodocs” build profile is enabled) just work by default? Or do we need > > some specific change to the Debian package? Could you give me an example of such a package? I'd be happy to investigate. > I also wonder about this :-) Unfortunately, in the case of Elpy, > dh_sphinxdoc does not find the documentation, and specifying a subdir > only limits the search for documentation to that dir.: >dh_sphinxdoc -O--buildsystem=pybuild > dh_sphinxdoc: Sphinx documentation not found > > > Is there generic Debian package maintainer advice that can be given – > > specific things to put in ‘/debian/rules’, etc. – to let “nodocs” work > > as designed? See solution at bottom. Where would be a convenient location for such documentation? Convenient, because convenience helps with adoption ;-) > Yes, this would be very much appreciated! > > I followed a Debian Python Team wiki page on the topic and am > currently using the following in debian/rules: > > override_dh_auto_build: > > dh_auto_build > PYTHONPATH=. sphinx-build -N -bman docs/ build/man # Manpage generator > PYTHONPATH=. sphinx-build -N -btexinfo docs/ build/info > makeinfo --no-split build/info/Elpy.texi -o build/info/elpy.info > > It was trivially easy to figure out how to build info pages, based on > the manpage generator example. > > I imagine something like wrapping the relevant sections of the > overridden dh_auto_build with a conditional check would do the trick, > but I haven't yet found an example, nor documentation of "nodocs". > eg: > > override_dh_auto_build: > > dh_auto_build > ifeq ($(nodocs),"YET_UNKNOWN_VALUE_SHOULD_EVAL_FALSE_FOR_NORMAL_BUILD") > PYTHONPATH=. sphinx-build -N -bman docs/ build/man # Manpage generator > PYTHONPATH=. sphinx-build -N -btexinfo docs/ build/info > makeinfo --no-split build/info/Elpy.texi -o build/info/elpy.info > endif > > The trouble is there are no booleans in Makefiles, and an undefined > variable doesn't eval to nil like in LISPs. So I don't know how to > proceed. I trivially adapted the--I think it was stage 1 bootstrapping--example from the BuildProfiles specification page. Another caveat I encountered was that it isn't documented that these changes should be tested with "DEB_BUILD_PROFILES=nodoc gbp buildpackage", or builder-of-choice instead of "gbp buildpackage", and that the builder would pass through the envvar to dpkg-buildpackage. "export DEB_BUILD_PROFILES=nodoc ; gbp buildpackage" does not work, although I expect "DEB_BUILD_PROFILES=nodoc ; export DEB_BUILD_PROFILES ; gbp buildpackage" should. --- debian/changelog | 6 ++ debian/control | 4 ++-- debian/rules | 8 +++- 3 files changed, 15 insertions(+), 3 deletions(-) diff --git a/debian/changelog b/debian/changelog index b62b11d..4f74bab 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,9 @@ +elpy (1.24.0-2) UNRELEASED; urgency=medium + + * Support 'nodoc' build profile. + + -- Nicholas D Steeves Tue, 04 Sep 2018 18:10:11 -0400 + elpy (1.24.0-1) unstable; urgency=medium * New upstream version. diff --git a/debian/control b/debian/control index 5bd04d3..f130ed3 100644 --- a/debian/control +++ b/debian/control @@ -27,8 +27,8 @@ Build-Depends: debhelper (>= 11~) , python3-mock , python3-nose , python3-pip - , python3-sphinx - , texinfo + , python3-sphinx + , texinfo Standards-Version: 4.2.1 Vcs-Browser: https://salsa.debian.org/emacsen-team/elpy Vcs-Git: https://salsa.debian.org/emacsen-team/elpy.git diff --git a/debian/rules b/debian/rules index a9d70b4..bd4c218 100755 --- a/debian/rules +++ b/debian/rules @@ -11,7 +11,13 @@ export LC_ALL # docs are not generated without this override override_dh_auto_build: dh_auto_build - PYTHONPATH=. sphinx-build -N -bman docs/ build/man # Manpage generator +# support the nodoc build profile +ifneq ($(filter nodocs,$(DEB_BUILD_PROFILES)),) + echo -e "\nnodoc build profile enabled, therefor not building docs.\n" +else + PYTHONPATH=. sphinx-build -N -bman docs/ build/man PYTHONPATH=. sphinx-build -N -btexinfo docs/ build/info makeinfo --no-split build/info/Elpy.texi -o
Re: Avoid building Sphinx documentation on request (was: Bug#905750: RFS: elpy/1.23.0-1)
On Fri, Aug 10, 2018 at 06:02:14AM +1000, Ben Finney wrote: > Chris Lamb writes: > > > * You should probably avoid building the documentation too if the > >nodocs build profile is enabled. > > For packages from PyPI which have documentation detectable by > ‘dh_sphinxdoc’, does this (avoid building the documentation if the > “nodocs” build profile is enabled) just work by default? Or do we need > some specific change to the Debian package? I also wonder about this :-) Unfortunately, in the case of Elpy, dh_sphinxdoc does not find the documentation, and specifying a subdir only limits the search for documentation to that dir.: dh_sphinxdoc -O--buildsystem=pybuild dh_sphinxdoc: Sphinx documentation not found > Is there generic Debian package maintainer advice that can be given – > specific things to put in ‘/debian/rules’, etc. – to let “nodocs” work > as designed? Yes, this would be very much appreciated! I followed a Debian Python Team wiki page on the topic and am currently using the following in debian/rules: override_dh_auto_build: dh_auto_build PYTHONPATH=. sphinx-build -N -bman docs/ build/man # Manpage generator PYTHONPATH=. sphinx-build -N -btexinfo docs/ build/info makeinfo --no-split build/info/Elpy.texi -o build/info/elpy.info It was trivially easy to figure out how to build info pages, based on the manpage generator example. I imagine something like wrapping the relevant sections of the overridden dh_auto_build with a conditional check would do the trick, but I haven't yet found an example, nor documentation of "nodocs". eg: override_dh_auto_build: dh_auto_build ifeq ($(nodocs),"YET_UNKNOWN_VALUE_SHOULD_EVAL_FALSE_FOR_NORMAL_BUILD") PYTHONPATH=. sphinx-build -N -bman docs/ build/man # Manpage generator PYTHONPATH=. sphinx-build -N -btexinfo docs/ build/info makeinfo --no-split build/info/Elpy.texi -o build/info/elpy.info endif The trouble is there are no booleans in Makefiles, and an undefined variable doesn't eval to nil like in LISPs. So I don't know how to proceed. Cheers, Nicholas signature.asc Description: PGP signature
Bug#905750: RFS: elpy/1.23.0-1
[Not prematurely sending mail this time] Nicholas, Alas I wrote before, whilst I appreciate the sentiment, please spend any limited time you have for Debian work writing such things in suitable venue(s) and not in an adjunct sponsorship bug. Otherwise I fear the effort expended in such a voluminous and detailed response will be in vain. > > * Please fix "wrong-section-according-to-package-name" on your next > >upload (or otherwise fix Lintian). > > This is currently an Informational level message. When it was a > Warning I declared Section: lisp, even though I do not believe that > this is accurate. Please strive to be Lintian clean not fuss about "warning" about "informational" which are not subject to strict scrutinity and classification by the Lintian maintainers as you seem to infer. > Re: fixing Lintian, this will require a discussion and a more clear > definition of Section: lisp. Most Emacs modes should probably be in > Section: editors, because they are interactive extensions to an > editor. Magit is definitely in the right section eg: vcs. Emacs > packages that enable IDE modes should be in Section: devel. > > Section: lisp should be reserved for libraries like dash-el. This is a topic for elsewhere. > > * gzip -9 might need to be gzip -9n for a reproducible build > >(unchecked) but I'm surprised it's not compressed by another tool > >too (unchecked). > > Thank you for pointing this out. I've reverted @commit:9095c18 > because README.rst is only 2.8k and dh_compress already does the > right thing automatically; that is to say, README.rst is not > "larger than 4k in size" and should not be compressed. ?? I was talking about -n, not -9. Nothing to do with 4k limits but rather reproducibly. > > On the topic of reproducibility, generating an info page made Elpy > unreproducible! > https://tests.reproducible-builds.org/debian/rb-pkg/unstable/amd64/elpy.html > > This will take time to look into. Possibilities are: > 1) sphinx-build is at fault > 2) makeinfo is at fault > 3) something is missing how I'm using 1 and/or 2. > - if this is the case then it's also a case of incomplete >documentation Likely #2 or something similar. https://bugs.debian.org/826158? But again, this is really the wrong venue for these 4/5 topics as it will quickly get lost.. Regards, -- ,''`. : :' : Chris Lamb `. `'` la...@debian.org / chris-lamb.co.uk `-
Bug#905750: RFS: elpy/1.23.0-1
Nicholas, > > For your wishlist/TODO: > > > > * Please fix "wrong-section-according-to-package-name" on your next > >upload (or otherwise fix Lintian). > > This is currently an Informational level message. When it was a > Warning I declared Section: lisp, even though I do not believe that > this is accurate. > > Re: fixing Lintian, this will require a discussion and a more clear > definition of Section: lisp. Most Emacs modes should probably be in > Section: editors, because they are interactive extensions to an > editor. Magit is definitely in the right section eg: vcs. Emacs > packages that enable IDE modes should be in Section: devel. > > Section: lisp should be reserved for libraries like dash-el. > > > * You should probably avoid building the documentation too if the > >nodocs build profile is enabled. > > I've added it to my TODO and will start learning about how to do > this. > > > * gzip -9 might need to be gzip -9n for a reproducible build > >(unchecked) but I'm surprised it's not compressed by another tool > >too (unchecked). > > Thank you for pointing this out. I've reverted @commit:9095c18 > because README.rst is only 2.8k and dh_compress already does the > right thing automatically; that is to say, README.rst is not > "larger than 4k in size" and should not be compressed. That's not what I was talking about, ie. "reproducibility". > On the topic of reproducibility, generating an info page made Elpy > unreproducible! > https://tests.reproducible-builds.org/debian/rb-pkg/unstable/amd64/elpy.html > > This will take time to look into. Possibilities are: > 1) sphinx-build is at fault > 2) makeinfo is at fault > 3) something is missing how I'm using 1 and/or 2. > - if this is the case then it's also a case of incomplete >documentation > Regards, -- ,''`. : :' : Chris Lamb `. `'` la...@debian.org / chris-lamb.co.uk `-
Bug#905750: RFS: elpy/1.23.0-1
Hi Chris, Thank you for sponsoring and reviewing! Reply follows inline. On Thu, Aug 09, 2018 at 08:06:43AM +0100, Chris Lamb wrote: > For your wishlist/TODO: > > * Please fix "wrong-section-according-to-package-name" on your next >upload (or otherwise fix Lintian). This is currently an Informational level message. When it was a Warning I declared Section: lisp, even though I do not believe that this is accurate. Re: fixing Lintian, this will require a discussion and a more clear definition of Section: lisp. Most Emacs modes should probably be in Section: editors, because they are interactive extensions to an editor. Magit is definitely in the right section eg: vcs. Emacs packages that enable IDE modes should be in Section: devel. Section: lisp should be reserved for libraries like dash-el. > * You should probably avoid building the documentation too if the >nodocs build profile is enabled. I've added it to my TODO and will start learning about how to do this. > * gzip -9 might need to be gzip -9n for a reproducible build >(unchecked) but I'm surprised it's not compressed by another tool >too (unchecked). Thank you for pointing this out. I've reverted @commit:9095c18 because README.rst is only 2.8k and dh_compress already does the right thing automatically; that is to say, README.rst is not "larger than 4k in size" and should not be compressed. On the topic of reproducibility, generating an info page made Elpy unreproducible! https://tests.reproducible-builds.org/debian/rb-pkg/unstable/amd64/elpy.html This will take time to look into. Possibilities are: 1) sphinx-build is at fault 2) makeinfo is at fault 3) something is missing how I'm using 1 and/or 2. - if this is the case then it's also a case of incomplete documentation Sincerely, Nicholas signature.asc Description: PGP signature
Avoid building Sphinx documentation on request (was: Bug#905750: RFS: elpy/1.23.0-1)
Chris Lamb writes: > * You should probably avoid building the documentation too if the >nodocs build profile is enabled. For packages from PyPI which have documentation detectable by ‘dh_sphinxdoc’, does this (avoid building the documentation if the “nodocs” build profile is enabled) just work by default? Or do we need some specific change to the Debian package? Is there generic Debian package maintainer advice that can be given – specific things to put in ‘/debian/rules’, etc. – to let “nodocs” work as designed? -- \ “Either he's dead or my watch has stopped.” —Groucho Marx | `\ | _o__) | Ben Finney
Bug#905750: RFS: elpy/1.23.0-1
tags 905750 + pending thanks Nicholas, > I am looking for a sponsor for my package "elpy" Uploaded elpy_1.23.0-1_amd64.changes. For your wishlist/TODO: * Please fix "wrong-section-according-to-package-name" on your next upload (or otherwise fix Lintian). * You should probably avoid building the documentation too if the nodocs build profile is enabled. * gzip -9 might need to be gzip -9n for a reproducible build (unchecked) but I'm surprised it's not compressed by another tool too (unchecked). Regards, -- ,''`. : :' : Chris Lamb `. `'` la...@debian.org / chris-lamb.co.uk `-
Bug#905750: RFS: elpy/1.23.0-1
Package: sponsorship-requests Severity: normal Dear mentors, I am looking for a sponsor for my package "elpy" Hi Chris, I've CCed you because you've sponsored past releases. Package name: elpy Version : 1.23.0-1 Upstream Author : Jorgen Schaefer URL : https://github.com/jorgenschaefer/elpy License : GPL-3+ Section : devel It builds this binary package: elpa-elpy - Emacs Python Development Environment To access further information about this package, please visit the following URL: https://mentors.debian.net/package/elpy Alternatively, one can download the package with dget using this command: dget -x https://mentors.debian.net/debian/pool/main/e/elpy/elpy_1.23.0-1.dsc Alternatively, clone its repository using this command: git clone https://salsa.debian.org/emacsen-team/elpy.git Changes since the last upload: elpy (1.23.0-1) unstable; urgency=medium * New upstream version. * Build and install info page. * Declare Standards-Version: 4.2.0 - §12.7, Install NEWS.rst as NEWS. * Add "Local Variables" footer to NEWS so that it opens in ReST mode. * Compress README.rst with gzip before installing. -- Nicholas D Steeves Wed, 08 Aug 2018 16:04:52 -0400 elpy (1.22.0-1) unstable; urgency=medium Regards, Nicholas D Steeves
