Rationalise documentation

[widdowquinn]

Summary:

We'd like to rationalise the documentation to make our lives, and users' lives, easier.

Description:

Some of the existing documentation is possibly overlong/in the "wrong" place, so we might consider three strands of documentation going forward:

• ReadTheDocs
  • these are canonical user-level docs
  • how do you install (in detail)
  • how do you use each command (in detail)
  • how do you perform analyses (in detail)
• README.md
  • this is a brief description of/introduction to the package/software
  • how do you install it?
  • how do you use it?
  • who wrote it?
  • what is the licence?
  • where are the docs?
  • where can I get help?
  • what if I want to contribute?
• Wiki
  • these are intended to be relatively dynamic documents, mostly related to development, but with some user support
  • user-facing stuff, like FAQs etc. might start on the wiki, but migrate to RTD over time
  • what is the project roadmap?
  • what are our coding style choices?
  • how do we do tests/logging/etc.?
  • how do we manage issues, etc?
  • how do we integrate with CI/project management tools, etc.?

[baileythegreen]

The current README has this table of contents:

Table of Contents

• pyani
  • Contributing
  • Contributors ✨ (emoji key):
  • Citing pyani
  • Table of Contents
  • Overview
  • Installation
  • IMPORTANT NOTICE
  • Documentation for stable version pyani v0.2.x
  • conda
  • pip
  • Third-party tools
  • NOTE: Installing legacy BLAST
  • Documentation (v0.3)
  • Older documentation (v0.2)
  • Bugs, issues, problems and questions
  • Walkthrough: A First Analysis
  • 1. Download genome data
  • 2. Create an analysis database
  • 3. Conduct ANI analysis
    • Rerunning the same analysis
  • 4. Reporting Analyses and Analysis Results
  • 5. Generating graphical output for ANI
  • 6. Classifying Genomes from Analysis Results
  • Using a scheduler
  • SGE/OGE
  • Running pyani version 0.2.x
  • Script: average_nucleotide_identity.py
  • Script: genbank_get_genomes_by_taxon.py
  • Method and Output Description
  • Average Nucleotide Identity (ANI)
  • Licensing

@widdowquinn From the conversation the other day, and the outline in the wiki, I think these sections of the README should be reduced/moved elsewhere:

---

The non-standard installation details could go into the wiki.

• Installation

  • IMPORTANT NOTICE
  • Documentation for stable version pyani v0.2.x
  • conda
  • pip
  • Third-party tools
  • NOTE: Installing legacy BLAST

    ---

    This might go into too much detail for the README, especially if it should eventually also detail SLURM stuff.

• Using a scheduler

  • SGE/OGE

    ---

    (This one maybe needs to stay; it depends a bit on the default version of pyani for the repo, I think.)

  • Running pyani version 0.2.x

  • Script: average_nucleotide_identity.py

  • Script: genbank_get_genomes_by_taxon.py

    ---

This section seems like it should either come earlier in the README, or be in the wiki:

• Method and Output Description
  • Average Nucleotide Identity (ANI)

[peterjc]

See also the CONTRIBUTING.md convention encouraged by GitHub which would hold or at least point to developer centric information like coding style, CI setup, issue management.