search

levitsky / pyteomics

Pyteomics is a collection of lightweight and handy tools for Python that help to handle various sorts of proteomics data. Pyteomics provides a growing set of modules to facilitate the most common tasks in proteomics data analysis.
http://pyteomics.readthedocs.io
Apache License 2.0
105 stars 34 forks source link

Improve documentation of Unimod loading and highlight in ProForma #85

Closed mobiusklein closed 1 year ago

mobiusklein commented 1 year ago

This PR implements some of the changes discussed in #82 but does not outright bundle the CV source file with the codebase. It adds documentation about how the CV can be loaded from disk instead of the internet.

It also re-structures the pyteomics.proforma documentation a bit and in need of a bit meditation I wrote a fragments method for the Proforma type.

levitsky commented 1 year ago

This looks great, thank you so much!

Just so I understand, what is the reason for duplicating the documentation from the source in the RST file? And is it related to the problem that I am having with latest Sphinx which pollutes the TOC with all the names from the documented modules? I couldn't find any information about the changes that cause it, but I can see that it's not happening with the proforma and unimod modules now that they are not using automodule.

Edit: Found sphinx-doc/sphinx#6316 which seems relevant.

mobiusklein commented 1 year ago

I copied the docstrings because I cannot figure out how to tell autodoc's automodule directive to just copy the module docstring and not list out the module members too. I couldn't make :no-members: or limiting it to only a subset of members. In order for the classes to be laid out in a way that isn't overwhelming to the reader.

I needed to disable automodule so I could intersperse them with prose to explain why there are all these classes but the only thing they need to really worry about is the functional API or the ProForma object.

levitsky commented 1 year ago

I feel like a lot of other documentation should be reworked for readability as well (outside of this PR, of course).

Do you think the module docstrings should be kept still? My concern is, the two versions will diverge; also I am not sure if anyone really benefits from the module-level documentation being there (unlike members' documentation, which often helps in interactive environments).

mobiusklein commented 1 year ago

I removed the complicated module docstring content. I declined to put an actual URL to the docs in the docstring because I didn't know if you have persistent URL set up.

While I was at it I added a test for the new fragments method and made it 2.5x faster.

levitsky commented 1 year ago

Thank you!