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

Improve documentation of Unimod loading and highlight in ProForma #85

Merged
merged 4 commits into from Oct 28, 2022

Conversation

mobiusklein
Copy link
Contributor

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
Copy link
Owner

levitsky commented Oct 26, 2022

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
Copy link
Contributor Author

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
Copy link
Owner

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
Copy link
Contributor Author

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 levitsky merged commit 1374e5e into levitsky:master Oct 28, 2022
@levitsky
Copy link
Owner

Thank you!

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

Successfully merging this pull request may close these issues.

None yet

2 participants