search

biopython / biopython.github.io

Source of biopython.org website, migrated from MediaWiki
biopython.org
150 stars 260 forks source link

Brute force Checklist. #38

Open vincentdavis opened 8 years ago

vincentdavis commented 8 years ago

As suggested by Markus Piotrowski Checklist:

  1. Title
  2. Is the text up-to-date? (Python versions etc)
  3. Formatting
  4. Suggestion: Python/Biopython commands, keywords, module/function names should be formatted as inline-code with single backticks, e.g. Bio.SeqIO ??? Or bold???
  5. If applicable, they can also serve as links to the respective Wiki page
  6. Code output and command-line examples should be formatted as block code with three backticks instead of several single line inline-code statements.
  7. Check block code for trailing white spaces, which may result in the addition of an (unnecessary) horizontal scrollbars as here: http://biopython.org/wiki/ACE_contig_to_alignment.
  8. Code
  9. Code should be checked for a minimum of PEP8 compliance.
  10. The code should work (as it is) under Biopython 1.66
  11. Since we are recommending Python 3.5 as environment, the code should work under Python 3.5 ???
  12. Links
  13. Check all links
  14. 'Repair' broken links Try to find a link that's more likely to be stable. E.g. for papers I think that dx.doi.org references (or Pubmed references) are more stable than linking to a special page of the respective journal or private or institutional homepages. With http://www.crossref.org/SimpleTextQuery/ you can do a reverse doi lookup for a given paper.
  15. Links with anchors (.../some_page#jump_here) may have issues with upper/lowercase formatting (https://github.com/biopython/biopython.github.io/issues/13)
  16. Are the links up-to-date? E.g. in http://biopython.org/wiki/Getting_Started the Python Quick Reference links to Python 2.5
  17. References
  18. Some pages used a PubMed plugin under MediaWiki to display references (https://github.com/biopython/biopython.github.io/issues/12). Since it's unlikely (?) to have a functional replacement, I would suggest to convert them to simple links.
  19. RSS feeds
  20. As above, embedding an existing RSS feed seems hard (https://github.com/biopython/biopython.github.io/issues/4), again I would suggest replace with a link pointing to the RSS feed
peterjc commented 8 years ago

Yes, as with the main Tutorial and docstrings, try to make code examples work on both Python 2 and 3 (using simple print functions with one variable). If not easy, I think it is time to prefer Python 3 syntax but perhaps the example should not this explicit for the lingering Python 2 users.

MarkusPiotrowski commented 8 years ago

Internal links with anchors: See also #13

The correct format for anchored links in the Wiki pages is "all lower case with hyphens", e.g. http://biopython.org/wiki/Publications#publications-from-2001

Each heading has such an anchor, so you can easily jump/link to any heading you like.