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: expand base template and improve descriptions #209

Merged
merged 23 commits into from
Jun 26, 2023
Merged

docs: expand base template and improve descriptions #209

merged 23 commits into from
Jun 26, 2023

Conversation

jsstevenson
Copy link
Member

@jsstevenson jsstevenson commented May 19, 2023

This PR covers a few documentation-related aspirations

  • Iterates on what I'd propose for the "Wagner lab template". Employs a new theme, Furo, which I think looks better. Adds some new Sphinx plugins and tries to use better ReST.
  • Adds a live graph figure to the normalization page, and provides a script to generate it. I haven't incorporated this into the Makefile since it's one script but that could be done if the scripts directory grows.
  • Small documentation tweaks to improve API descriptions
  • Updates OpenAPI stuff. We were previously using a bit of an indirect way to define some metadata.
  • Added a tests and min. python version badge

Also we can close #185, close #206

A few discussion points/possible todo's:

  • The Furo theme is pretty easily customizable (a big reason why I think we should stick with Sphinx instead of moving over to Mkdocs, even though I really like the Material mkdocs theme). I haven't altered the default colors here but we could definitely put together a lab theme (@katiestahl ?) at some point. We also need to figure out a way to alter the figure's CSS.
  • It'd be great to incorporate some of @anastasiasmith1221's work on gene terms as it develops: for example, in a "recipes/cookbook" type section (i.e., here's an example of some code using the gene normalizer to do a big analysis project), and/or in a "here is the problem" section (i.e. here are examples of ambiguities in references that lend themselves to normalization)
  • I wanted to do a short blurb on VRS somewhere if it seemed relevant
  • I would prefer that subsection indexes don't exist but I'm not sure if I can turn this off
  • Mention difference between 0.1.x and 0.2.x

btw, PRs should now trigger new readthedocs builds, so you can check out how this would look here: https://gene-normalizer--209.org.readthedocs.build/en/209/

@jsstevenson jsstevenson marked this pull request as ready for review May 19, 2023 19:28
@korikuzma
Copy link
Member

@jsstevenson what's the priority on this PR?

@jsstevenson
Copy link
Member Author

@korikuzma very low

@jsstevenson jsstevenson added the priority:low Low priority label May 26, 2023
@@ -0,0 +1,22 @@
Sources
=======

Copy link
Member Author

Choose a reason for hiding this comment

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

I think it might make more sense to move the Gene record summary over to this page, and put GeneDescriptor on the normalization page

Copy link
Member

Choose a reason for hiding this comment

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

Or even having sections for search, normalize, and normalize_unmerge?

Copy link
Member

@korikuzma korikuzma left a comment

Choose a reason for hiding this comment

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

Only requesting change for the seqrepo path because I think it was a typo. This is coming together quite nicely! I do agree it would be nice to have a little section about VRS and how we support different versions

requirements.txt Outdated
Copy link
Member

Choose a reason for hiding this comment

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

I know it's not part of this issue, but you can remove the requirements in this PR if you want. Or we can do it in a separate issue

docs/source/full_install.rst Outdated Show resolved Hide resolved
docs/source/index.rst Outdated Show resolved Hide resolved
docs/source/index.rst Outdated Show resolved Hide resolved
@@ -0,0 +1,22 @@
Sources
=======

Copy link
Member

Choose a reason for hiding this comment

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

Or even having sections for search, normalize, and normalize_unmerge?

@jsstevenson jsstevenson merged commit 4314eb4 into main Jun 26, 2023
21 checks passed
@jsstevenson jsstevenson deleted the furo branch June 26, 2023 12:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
priority:low Low priority
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Provide thorough description of source data Set up docs deployment
2 participants