Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sphinx API documentation missing __magic__ methods #2502

Closed
peterjc opened this issue Jan 7, 2020 · 6 comments
Closed

Sphinx API documentation missing __magic__ methods #2502

peterjc opened this issue Jan 7, 2020 · 6 comments

Comments

@peterjc
Copy link
Member

peterjc commented Jan 7, 2020

e.g. https://biopython.org/docs/dev/api/Bio.Seq.html and https://biopython.org/docs/1.76/api/Bio.SeqRecord.html are missing the __getitem__ documentation which describes slicing etc.

Compare with https://biopython.org/DIST/docs/api/Bio.Seq.Seq-class.html (generated with epydoc, which we intend to drop.

This is likely down to a miss-configuration in https://github.com/biopython/biopython/blob/master/Doc/api/conf.py

To build the documentation locally (see also #1803), use:

pip install tox
tox -c .travis-tox.ini -e api
open Doc/api/_build/html/index.html
@peterjc
Copy link
Member Author

peterjc commented Jan 7, 2020

Hmm, we have this in conf.py, which ought to show the special methods:

# This requires Sphinx 1.8.0b1 or later:
autodoc_default_values = {
    "members": None,
    "undoc-members": None,
    "special-members": None,
    "show-inheritance": None,
    "member-order": "bysource",
    "exclude-members": "__dict__,__weakref__,__module__",
}

Might be down to the version of Sphinx...

@peterjc
Copy link
Member Author

peterjc commented Jan 7, 2020

Looking at the most recent master build,
https://travis-ci.org/biopython/biopython/jobs/633717043

Tox installed:

alabaster==0.7.12,Babel==2.8.0,certifi==2019.11.28,chardet==3.0.4,docutils==0.15.2,idna==2.8,imagesize==1.2.0,isodate==0.6.0,Jinja2==2.10.3,MarkupSafe==1.1.1,mmtf-python==1.1.2,msgpack==0.6.2,mysql-connector-python-rf==2.2.2,numpy==1.18.1,numpydoc==0.9.2,packaging==20.0,Pillow==7.0.0,Pygments==2.5.2,pyparsing==2.4.6,pytz==2019.3,rdflib==4.2.2,reportlab==3.5.32,requests==2.22.0,scipy==1.4.1,six==1.13.0,snowballstemmer==2.0.0,Sphinx==2.3.1,sphinx-rtd-theme==0.4.3,sphinxcontrib-applehelp==1.0.1,sphinxcontrib-devhelp==1.0.1,sphinxcontrib-htmlhelp==1.0.2,sphinxcontrib-jsmath==1.0.1,sphinxcontrib-qthelp==1.0.2,sphinxcontrib-serializinghtml==1.1.3,urllib3==1.25.7

And to be clear, it said:

Running Sphinx v2.3.1

Looking back, even https://biopython.org/docs/1.74/api/Bio.SeqRecord.html had this problem - perhaps the configuration used only worked with a specific 1.8.0b1 era version of Sphinx.

@chebizarro
Copy link
Contributor

It looks like the variable name was changed to be autodoc_default_options after 1.8 - https://www.sphinx-doc.org/en/2.0/usage/extensions/autodoc.html - changing this in conf.py produces the expected results for me (sphinx v. 2.2.1). I can submit a pull request shortly.

@peterjc
Copy link
Member Author

peterjc commented May 8, 2020

That is simple but subtle - I'm glad someone spotted it. Thank you!

@peterjc
Copy link
Member Author

peterjc commented May 8, 2020

Here's where autodoc_default_options was added on the main branch, sphinx-doc/sphinx@3d9e2cf

I suppose the other form autodoc_default_values must have been specific to the branch the beta release was made from?

@peterjc
Copy link
Member Author

peterjc commented May 8, 2020

Confirming the fix worked, https://biopython.org/docs/dev/api/Bio.Seq.html etc look good. Thank you @chebizarro 👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants