peterjc
commented
1 month ago Ah. This isn't part of the human-written API docstrings, but rather Sphinx automatically trying to document the public attributes of the class. That is currently defined as:
class DataHandler(metaclass=DataHandlerMeta):
"""Data handler for parsing NCBI XML from Entrez."""
from Bio import Entrez
global_dtd_dir = os.path.join(Entrez.__path__[0], "DTDs")
global_xsd_dir = os.path.join(Entrez.__path__[0], "XSDs")
local_dtd_dir = None
local_xsd_dir = None
del Entrez
...The code is explicitly setting the global values relative to the location of the Python code (because we install some DTD and XSD files there). In this content, that picks up some temp code location while the docs are being built.
I don't have an immediate answer for this.
There may be something we can tweak in Sphinx's API documentation code. Or, as you suggest, post-processing the documentation somewhere (e.g. with Python code within the Sphinx conf.py https://github.com/biopython/biopython/blob/master/Doc/conf.py perhaps).
Or, there may be a code change worth making here which might also avoid this, @mdehoon?
mr-c
emollier
Hi,
While trying to bump Biopython to version 1.84 in Debian sid, I tried to accomodate to the new way of preparing the documentation, dropping TeX in favor of Sphinx documentation in HTML. In the process, I hit a binary package reproducibility regression, which upon further analysis, points to injection of the package build path into the documentation. The issue is visible on the public documentation page, where circleci home directory appears explicitly in the class Bio.Entrez.Parser.DataHandler description:
I'm afraid that my understanding of tweaking Sphinx is too weak to devise a fix that does not interfere with the proper operation of the code. It may be possible to edit the documentation after the fact, using e.g. sed, but I'm concerned about failing to catch tokens making their way in the integrated search engine (I hit a similar issue in the past while working on the parsl module). Per chance, do you see a way how to mitigate the injection of the build path in the documentation?
Package building reproducibility not being a hard blocker in Debian yet, you can treat this as a wishlist item.
Have a nice day, :) Étienne.
Setup
I am reporting a problem with Biopython version, Python version, and operating system as follows:
Expected behaviour
I would like to avoid having unreproducible build path in the documentation.
Actual behaviour
Unreproducible build path appears in Bio.Entrez.Parser.DataHandler API documentation.
Steps to reproduce
Build the documentation: