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

docs: add documentation #222

Merged
merged 35 commits into from
Dec 26, 2023
Merged

docs: add documentation #222

merged 35 commits into from
Dec 26, 2023

Conversation

jsstevenson
Copy link
Member

@jsstevenson jsstevenson commented Dec 5, 2023

close #209 , address #11

Because of how many different things CST can do, I tried to embed a lot of explanation/instructions directly in the API reference rather than writing it out separately.

  • The sphinx docs test action that I'd been using is unfortunately not happy about psycopg2 and is also unhappy with every one of my attempts to install the binary manually. I've gone ahead and just done a basic manual test, but the logging won't be as pretty.
  • What do we think we should be saying about VRS conformance? Maybe just say that this version is consistent with 1.x? We could also leave it light for now and return in Return VRS objects where we can  #219 (could also wait until VRS 2 alpha branch is merged)
  • Left a few small TODOs/question marks scattered where I was unsure if I was giving a correct explanation
  • I think it might be cool to add an example script that uses some of the functions to do something cool (maybe some code extracted from the Variation Normalizer). Not urgently trying to get that added now unless anyone has a good idea.

@jsstevenson jsstevenson changed the base branch from main to staging December 22, 2023 16:04
@jsstevenson jsstevenson marked this pull request as ready for review December 22, 2023 16:04
cool_seq_tool/handlers/seqrepo_access.py Outdated Show resolved Hide resolved
cool_seq_tool/mappers/exon_genomic_coords.py Outdated Show resolved Hide resolved
Comment on lines 514 to 515
# TODO example
even though it's not public (it should be?)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I only see this method used in this class. If there's code similar to this in other places, we can move to utility functions

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


Try GRCh38 first, then GRCh37.

# TODO example for this?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you want to add examples in here or new issue?

cool_seq_tool/mappers/mane_transcript.py Outdated Show resolved Hide resolved
cool_seq_tool/sources/transcript_mappings.py Outdated Show resolved Hide resolved
cool_seq_tool/sources/uta_database.py Outdated Show resolved Hide resolved
docs/source/contributing.rst Show resolved Hide resolved
@jsstevenson
Copy link
Member Author

jsstevenson commented Dec 22, 2023

Remaining TODO

  • Make tests pass
  • Address comments above
  • Refine README
  • Fill out docs front page
  • Readthedocs deployment/integration
  • Refine language about async/maybe better examples?
  • Single to double sphinx ticks in docstrings

@jsstevenson jsstevenson mentioned this pull request Dec 26, 2023
Comment on lines 18 to 19
* "Validating reference sequences" # TODO what does this mean?
* "Validating exon structure" # TODO what does this mean?
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@korikuzma can you clarify these two lines? They're taken from the previous markdown docs file

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIRC validating reference sequences means ensuring actual reference sequence matches expected reference sequence for a given ac/pos. Exon structure has to deal with ensuring exon numbers are the same.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🙌

If unable to find a match on GRCh38, this method will then attempt to drop down
to GRCh37.

# TODO example for inputs that demonstrate this?
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@korikuzma do you have an example set of inputs handy for this?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not off the top of my head. We can make a separate issue if needed.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(sorry, this duplicates a comment you had above. Probably not necessary if there isn't a good example available -- I was just trying to illustrate different code branches based on input)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No worries. It is good to have an example and see if our test suite covers it. I just don't know off the top of my head and would have to dig into the test data

@jsstevenson jsstevenson merged commit 28e99a9 into staging Dec 26, 2023
12 checks passed
@jsstevenson jsstevenson deleted the new-docs branch December 26, 2023 19:00
@korikuzma korikuzma mentioned this pull request Dec 27, 2023
2 tasks
korikuzma pushed a commit that referenced this pull request Jan 9, 2024
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.

Update docstrings + remove types
2 participants