pyani
pyani copied to clipboard
Rationalise documentation
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.?
- these are intended to be relatively dynamic documents, mostly related to development, but with some user support
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
-
Script:
-
Method and Output Description
- Average Nucleotide Identity (ANI)
- Licensing
-
Contributing
@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
-
Script:
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)
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.