Building documentation on Debian: warnings and failure

[lopippo]

Greetings,

I would like to build pymzML for the Debian python3-pymzml package, but when following the build.command recipe, this is what I get:

% make html:

reading sources... [100%] suppl_material
../README.rst:4: WARNING: Duplicate explicit target name: "here".
/home/rusconi/devel/python-pymzml/tarballs/pymzml-repack-2.5.2/pymzml/plot.py:docstring of pymzml.plot.Factory.add:6: ERROR: Unexpected indentation.
/home/rusconi/devel/python-pymzml/tarballs/pymzml-repack-2.5.2/pymzml/plot.py:docstring of pymzml.plot.Factory.add:15: ERROR: Unexpected indentation.

This warning is not serious because the documentation is built fine.

Then when doing

% make latexpdf

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
processing pymzML.tex... index intro quick_start modules pymzml_run pymzml_spec pymzml_utils plot file_handlers obo pymzml_regex_patterns examples index_gzip custom_fileclass example_scripts suppl_material
resolving references...
failed

Extension error:
convert exited with error:
[stderr]
b'convert convert: Unable to read font (/usr/share/fonts/type1/gsfonts/n019003l.pfb) [No such file or directory].\n'
[stdout]

I was wondering if that font file was required or if some config bit could change it. That font file does not belong in any font package in Debian, which makes things a bit complex... Does that font choice depend on your doc code or is it encoded by sphinx (or by who knows)?

Thank you for listening :-)

Filippo

[lopippo]

After having researched a bit, I discovered that that font file is actually n019003l.pfb: Nimbus Sans L:style=Regular that seems equivalent to /usr/share/fonts/X11/Type1/NimbusSans-Regular.pfb: Nimbus Sans:style=Regular. Do you have an idea where we could make the change ?
Filippo

[lopippo]

I managed to create a symlink /usr/share/fonts/X11/Type1/NimbusSans-Regular.pfb -> n019003l.pfb.

but the the documentation build fails differently:

Chapter 1.
(/usr/share/texlive/texmf-dist/tex/latex/txfonts/t1txtt.fd)
Runaway argument?
{\sphinxincludegraphics {{code
! Paragraph ended before \sphinxhref was complete.

\par
l.100

?

If I enter 'q', then the build goes on.

If I run that make latexpdf command twice (hitting 'q' twice), this is what I get (with the pdf file being generated seemingly succesfully):

? q
OK, entering \batchmodeLatexmk: Getting log file 'pymzML.log'
Latexmk: Examining 'pymzML.fls'
Latexmk: Examining 'pymzML.log'
Latexmk: Index file 'pymzML.idx' was written
Latexmk: References changed.
Latexmk: Log file says output to 'pymzML.pdf'
Latexmk: Errors, so I did not complete making targets
Collected error summary (may duplicate other messages):
pdflatex: Command for 'pdflatex' gave return code 1
Refer to 'pymzML.log' for details
Latexmk: If appropriate, the -f option can be used to get latexmk
to try to force complete processing.
make[1]: *** [Makefile:29: pymzML.pdf] Error 12
make[1]: Leaving directory '/home/rusconi/devel/python-pymzml/tarballs/pymzml-repack-2.5.2-built/docs/build/latex'
make: *** [Makefile:141: latexpdf] Error 2

However, the problem, even if the pdf file seems to be correct, is that the make error provokes the Debian package build failure.

What do you think is involved in this error (that is, at this point I am stuck)?

Sincerely,
Filippo

[MKoesters]

Hi @lopippo,

We did not make the choice for this font explicitly (at least as far as I know).
In order to test this on debian, I'd need to set up a debian box which I could do and have a closer look if I can circumvent this or change this in the config somewhere.
I'll also have a look if I could change the font somewhere in the sphinx config
I'll let you know when I managed to build the pdf on debian!
You are using debian bullseye I guess?

And thank you for taking care of the debian package and reporting this!
When I finally manage to create a list of contributors, you definitely be in the list (if you want, of course)

Best,
Manuel

[lopippo]

Greetings, Manuel,
nice to hear from you (your team) again, after a longish time :-)

You are using debian bullseye I guess?

Well, we always build new versions of packages for Debian unstable (sid) and I always work on testing (that is, what will be the version after bullseye: bookworm). I would suggest this link :-) https://www.debian.org/devel/debian-installer/. I have installed a brand new machine recently and that was flawless!

Thank you for your endeavour on pymzML !
Sincerely,
Filippo

[lopippo]

Greetings, Manuel,

any advance on this issue? I would be glad to have this current version in Debian stable...
Sincerely,
Filippo

[lopippo]

OK, waiting for a more formal resolution, this is what I did:

cd docs

sudo mkdir -p /usr/share/fonts/type1/gsfonts

<download n019003l.pfb from the web>

sudo ln -sf ~/n019003l.pfb /usr/share/fonts/type1/gsfonts/n019003l.pfb

make latex

The output is the following (only warnings shown):

Running Sphinx v4.5.0
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [latex]: all documents
updating environment: 0 added, 9 changed, 0 removed
reading sources... [100%] quick_start                                                                                                                                                                                                                                         
/home/rusconi/devel/python-pymzml/development/pymzml/plot.py:docstring of pymzml.plot.Factory.add:6: ERROR: Unexpected indentation.
/home/rusconi/devel/python-pymzml/development/pymzml/plot.py:docstring of pymzml.plot.Factory.add:15: ERROR: Unexpected indentation.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
processing pymzML.tex... index intro quick_start modules pymzml_run pymzml_spec pymzml_utils plot file_handlers obo pymzml_regex_patterns examples index_gzip custom_fileclass example_scripts suppl_material 
resolving references...
WARNING: Could not fetch remote image: https://travis-ci.org/pymzml/pymzML.svg?branch=master [time data 'Fri, 04 Jun 2021 07:20:27 GMT' does not match format '%a, %d %b %Y %H:%M:%S %Z']
WARNING: Could not fetch remote image: https://img.shields.io/pypi/v/pymzML.svg [time data 'Mon, 12 Dec 2022 13:19:44 GMT' does not match format '%a, %d %b %Y %H:%M:%S %Z']
WARNING: Could not fetch remote image: https://pepy.tech/badge/pymzml [time data 'Mon, 12 Dec 2022 10:05:05 GMT' does not match format '%a, %d %b %Y %H:%M:%S %Z']
WARNING: Could not fetch remote image: https://img.shields.io/badge/code%20style-black-000000.svg [time data 'Mon, 12 Dec 2022 04:29:09 GMT' does not match format '%a, %d %b %Y %H:%M:%S %Z']
done
writing... done
copying images... [100%] http://depsy.org/api/package/pypi/pymzML/badge.svg                                                                                                                                                                                                   
copying TeX support files... copying TeX support files...
done
build succeeded, 6 warnings.

I do not know how grave these warnings are. The LaTeX code that is generated is nonetheless usable to craft a pdf file using the make latexpdf command.

However, for the building of Debian packages, the network accesses during the package building are prohibited and the image fetching above will create trouble while doing the building. Is it possible to somehow avoid any "live" build-time access to the network other than the downloading of dependencies in the form of debian packages?

Sincerely,
Filippo

[lopippo]

Going forward...

oddly enough, I now tried this command

sudo ln -sf /usr/share/fonts/X11/Type1/NimbusSans-Regular.pfb /usr/share/fonts/type1/gsfonts/n019003l.pfb

and then make latexpdf and the build went fine (unless for the problematic network accessses during the build mentioned in the previous issue message). So, that means that I should be able, while building the package, to make that symbolic link. Could you please, then, provide me with instructions to avoid accessing the network during the docs build step ?

Edit: I tried to look into the documentation source files and grepping appveyor or travis did not find anything. So, I wonder if these network accesses are actually coded in your documentation or if they are coded in the sphinx run time? Do you have any idea?

Thank you!
Sincerely,
Filippo

[lopippo]

Again, going forward:

I discovered that the actual documentation source files never mention appveyor or travis. These items get inserted in the pymzML.tex when building the latex version of the documentation. These are the lines:

\section{Introduction}
\label{\detokenize{intro:introduction}}\label{\detokenize{intro::doc}}
\sphinxhref{https://travis-ci.org/pymzml/pymzML}{}

\sphinxhref{https://ci.appveyor.com/api/projects/status/e5reb5xw74jfqk2v/branch/dev?svg=true}{\sphinxincludegraphics{{dev}.png}}

\sphinxhref{http://pymzml.readthedocs.io/en/latest/?badge=latest}{\sphinxincludegraphics{{7766b8f36f974d7f8b0e8f664acb84c7a0fb8f9e}.png}}

\sphinxhref{https://codecov.io/gh/pymzml/pymzml}{\sphinxincludegraphics{{badge}.png}}

\sphinxhref{https://pypi.org/project/pymzML/}{}

\sphinxhref{https://pepy.tech/project/pymzml}{}

\sphinxhref{https://github.com/psf/black}{}

\sphinxhref{http://depsy.org/package/python/pymzML}{\sphinxincludegraphics{{badge}.png}}

The problem here is that 'make latex' not only seems to write these lines but also somehow tries to resolve these references, like this:

resolving references...
WARNING: Could not fetch remote image: https://travis-ci.org/pymzml/pymzML.svg?branch=master [time data 'Fri, 04 Jun 2021 07:20:27 GMT' does not match format '%a, %d %b %Y %H:%M:%S %Z']
WARNING: Could not fetch remote image: https://img.shields.io/pypi/v/pymzML.svg [time data 'Mon, 12 Dec 2022 15:21:22 GMT' does not match format '%a, %d %b %Y %H:%M:%S %Z']
WARNING: Could not fetch remote image: https://pepy.tech/badge/pymzml [time data 'Mon, 12 Dec 2022 10:05:05 GMT' does not match format '%a, %d %b %Y %H:%M:%S %Z']
WARNING: Could not fetch remote image: https://img.shields.io/badge/code%20style-black-000000.svg [time data 'Sun, 11 Dec 2022 16:59:21 GMT' does not match format '%a, %d %b %Y %H:%M:%S %Z']

How can we disable the insertion of these network references?

Sincerely,
Filippo

[lopippo]

As for the two indentation errors, mentioned in my very first issue report message, here is something that does not make sphinx complain:

diff --git a/pymzml/plot.py b/pymzml/plot.py
index 853d76a..a98c409 100755
--- a/pymzml/plot.py
+++ b/pymzml/plot.py
@@ -123,14 +123,14 @@ class Factory(object):
         name=None,
         plot_num=-1,
         title=None,
-    ):
+        ):
         """
         Add data to the graph.
 
         Arguments:
             data (list): The data added to the graph. Must be list of  tuples with
-                the following format. Note that i can be set to 'max_intensity' for
-                setting the label position to the maximum intensity.
+            the following format. Note that i can be set to 'max_intensity' for
+            setting the label position to the maximum intensity.
                     *   (mz,i) for all styles, except label,
                     *   (mz,i, string) for label.hoverinfo, .sticks and .triangle
                     *   (mz1, mz2, i, string) for label.linear and .spline
@@ -138,6 +138,7 @@ class Factory(object):
         Keyword Arguments:
             color (tuple): color encoded in RGB. Default = (0,0,0)
             style (str): plotting style. Default = "sticks".
+
                 Currently supported styles are:
                     *   'lines':
                         Datapoints connected by lines

Is this correct ?

Sincerely,
Filippo

[MKoesters]

Hey,

Sorry for not answering, I'm in the midst of writing up my phD thesis and did not find the time.
I guess the links its trying to resolve are in the README, however I did not find where in the docs the README is included.
I'm really sorry that I cant help you, but I'd be able to merge a PR (even if its a workaround for the time being) if that helps you to get the package ready for debian.

E: README is included in sources/intro.rst
The links to the badges are probably what are causing the problems.
I think we are not using appveyor anymore anyways, so that could go.
I was also planning to move to github actions and remove travis too, but as I said, I'm quite short on time currently ..

Best,
Manuel

[MKoesters]

I'll try to find out how/where to insert something like a grep -v to remove the lines with the badges while building the docs with sphinx.
If that does not work, you might need to do it in your package build

[lopippo]

Greetings, Manuel,

thank you for helping. Yes, indeed, in the README.rst file (top source dir) there are all these images included that link to external web sites. I'll try to make a patch for the Debian packaging that removes these images and then rebuild. I'll report to you as soon as possible.
Sincerely,
Filippo