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 <lamby@debian.org> 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 <nsteeves@gmail.com> 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 <!nocheck>
, python3-nose <!nocheck>
, python3-pip <!nocheck>
- , python3-sphinx
- , texinfo
+ , python3-sphinx <!nodoc>
+ , texinfo <!nodoc>
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 build/info/elpy.info
cat NEWS.rst debian/local-var-snippet > build/NEWS
+endif
+
--
2.18.0
Attachment:
signature.asc
Description: PGP signature