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

Various improvements to readthedocs documentation #1853

Closed
heuermh opened this Issue Jan 3, 2018 · 1 comment

Comments

1 participant
@heuermh
Member

heuermh commented Jan 3, 2018

Suggestions for various improvements to readthedocs documentation:

  • Source code css style could be better (clearer difference between comments and code, no bold text)
  • CSS layout doesn't expand horizontally for wide browser windows
  • Can't read pipe method source without horizontal scrolling (this holds true for almost all code blocks)
  • http://adam.readthedocs.io/en/latest/_images/grdd.png is unreadable at normal size
  • ./bin/adam-submit flagstat NA12878_chr20.adam could drop the ./bin/ to match other examples
  • Java example on pipe API doc page doesn't read the same as other languages, doesn't have loadXxx
  • There is no reference for the formats schema, java classes, and product scala classes (although perhaps the latter will show up in the latest scaladoc?)
  • Figures on http://adam.readthedocs.io/en/latest/benchmarks/algorithms/ should use GATK4 as a label
  • Is it "GATK" or "the GATK"?
  • GATK in "...more performant than the same algorithms implemented in the GATK. ADAM outperforms the GATK when running..." should be GATK4
  • GATK4 comparison is missing in INDEL Realignment figure
  • Remove CGCloud section from deploying doc
  • Note that Conductor is not appropriate for uploading Parquet directories to S3 in http://adam.readthedocs.io/en/latest/deploying/cgcloud/#bulk-transfer-between-hdfs-and-s3, suggest s3a via AWS CLI or s3-dist-cp
  • Add deploying on EMR doc with example config
  • Drop ./bin/ in examples on http://adam.readthedocs.io/en/latest/deploying/yarn/
  • Bold fixed-width font in An example workflow: toil_scripts.adam_kmers.count_kmers is kind of obnoxious
  • Strange layout on http://adam.readthedocs.io/en/latest/api/adamContext/, note blank lines between "loadIndexedBam" and "(Scala only)"
  • Incorrect link anchor in RDDs are processed by running functional [transformations]{#transforming} across the whole dataset.
  • Split http://adam.readthedocs.io/en/latest/_images/join_examples.png into two figures
  • Nested bullets didn't work at AlignmentRecordRDD: InFormatters: SAMInFormatter and BAMInFormatter write SAM or BAM out to a pipe.
  • Mention Cannoli in http://adam.readthedocs.io/en/latest/api/pipes/
  • Links on http://adam.readthedocs.io/en/latest/downstream/overview/ do not work
  • Links on http://adam.readthedocs.io/en/latest/downstream/cli are not correct, e.g. http://adam.readthedocs.io/en/latest/downstream/cli/#build-new-command should be http://adam.readthedocs.io/en/latest/downstream/cli/#extend-the-adam-cli-by-adding-new-commands-in-an-external-repository
  • Should https://github.com/heuermh/adam-examples and https://github.com/heuermh/adam-commands be migrated to bigdatagenomics organization?
  • Left margin in BQSR read ←the read to observe block looks incorrect
  • Inline math formatting in RI reads mathbf{r}, we, l_s denotes and q_c value look incorrect
  • Should http://adam.readthedocs.io/en/latest/#introduction section be its own page, separate from the Table of Contents?
  • Should http://adam.readthedocs.io/en/latest/#references section be its own page?
  • Add https://github.com/bigdatagenomics/adam#citing-adam section or as new page
  • Index http://adam.readthedocs.io/en/latest/genindex/ is empty
  • Confirm http://adam.readthedocs.io/en/latest is actually the latest (git head)
  • Similar blank line problem with bullets on Table of Contents page, between BWA, and bowtie2, FreeBayes)
  • http://adam.readthedocs.io/en/latest/deploying/aws/ is missing from Table of Contents
  • RI inline doc refers to s(i) but I don't see it in the equation

@heuermh heuermh self-assigned this Jan 4, 2018

@heuermh heuermh added this to the 0.24.0 milestone Jan 9, 2018

@heuermh

This comment has been minimized.

Member

heuermh commented Jan 9, 2018

Finally, is what I'm currently seeing at http://adam.readthedocs.io/en/latest actually the latest (git head)? Doesn't appear so, will confirm.

This has been addressed.

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