[FEATURE] --help should include `__resources__` tags

ekiefl commented 3 years ago

The need

anvi-help produces great info about resources. So do the anvi'o help docs. It would be nice if when --help is used in a command, the information in the __resources__ variables was displayed.

The solution

argparse gymnastics

Beneficiaries

Everyone.

meren commented 3 years ago

Also it would be great to provide a link to the online resource for a given program (unless we want to implement a terminal Markdown viewer which we certainly should not) 😂

ekiefl commented 3 years ago

Also it would be great to provide a link to the online resource for a given program

This is the feature request. For example, right now we have:

▶▶ anvi-compute-gene-cluster-homogeneity -h
usage: anvi-compute-gene-cluster-homogeneity [-h] -p PAN_DB
                                             [-g GENOMES_STORAGE]
                                             [-o FILE_PATH] [--store-in-db]
                                             [--gene-cluster-id GENE_CLUSTER_ID]
                                             [--gene-cluster-ids-file FILE_PATH]
                                             [-C COLLECTION_NAME]
                                             [-b BIN_NAME]
                                             [--quick-homogeneity]
                                             [-T NUM_THREADS] [--just-do-it]

Compute homogeneity for gene clusters

optional arguments:
  -h, --help            show this help message and exit

INPUT FILES:
  Input files from the pangenome analysis.

  -p PAN_DB, --pan-db PAN_DB
                        Anvi'o pan database
  -g GENOMES_STORAGE, --genomes-storage GENOMES_STORAGE
                        Anvi'o genomes storage file

REPORTING:
  How do you want results to be reported? Anvi'o can produce a TAB-delimited
  output file for you (for which you would have to provide an output file
  name). Or the results can be stored in the pan database directly, for
  which you would have to explicitly ask for it. You can get both as well in
  case you are a fan of redundancy and poor data analysis practices. Anvi'o
  does not judge.

...

It would be great to have:

▶▶ anvi-compute-gene-cluster-homogeneity -h
usage: anvi-compute-gene-cluster-homogeneity [-h] -p PAN_DB
                                             [-g GENOMES_STORAGE]
                                             [-o FILE_PATH] [--store-in-db]
                                             [--gene-cluster-id GENE_CLUSTER_ID]
                                             [--gene-cluster-ids-file FILE_PATH]
                                             [-C COLLECTION_NAME]
                                             [-b BIN_NAME]
                                             [--quick-homogeneity]
                                             [-T NUM_THREADS] [--just-do-it]

Compute homogeneity for gene clusters

RESOURCES:

The role of gene cluster
homogeneity described in the Anvi'o pangenomics tutorial:
http://merenlab.org/2016/11/08/pangenomics-v2/#inferring-the-homogeneity-of-
gene-clusters

optional arguments:
  -h, --help            show this help message and exit

INPUT FILES:
  Input files from the pangenome analysis.

  -p PAN_DB, --pan-db PAN_DB
                        Anvi'o pan database
  -g GENOMES_STORAGE, --genomes-storage GENOMES_STORAGE
                        Anvi'o genomes storage file

REPORTING:
  How do you want results to be reported? Anvi'o can produce a TAB-delimited
  output file for you (for which you would have to provide an output file
  name). Or the results can be stored in the pan database directly, for
  which you would have to explicitly ask for it. You can get both as well in
  case you are a fan of redundancy and poor data analysis practices. Anvi'o
  does not judge.

...

ekiefl commented 3 years ago

OH you mean a link to the anvi'o help docs page, right?

▶▶ anvi-compute-gene-cluster-homogeneity -h
usage: anvi-compute-gene-cluster-homogeneity [-h] -p PAN_DB
                                             [-g GENOMES_STORAGE]
                                             [-o FILE_PATH] [--store-in-db]
                                             [--gene-cluster-id GENE_CLUSTER_ID]
                                             [--gene-cluster-ids-file FILE_PATH]
                                             [-C COLLECTION_NAME]
                                             [-b BIN_NAME]
                                             [--quick-homogeneity]
                                             [-T NUM_THREADS] [--just-do-it]

Compute homogeneity for gene clusters

WEBPAGE:

http://merenlab.org/software/anvio/help/programs/anvi-compute-gene-cluster-homogeneity/

RESOURCES:

The role of gene cluster
homogeneity described in the Anvi'o pangenomics tutorial:
http://merenlab.org/2016/11/08/pangenomics-v2/#inferring-the-homogeneity-of-
gene-clusters

optional arguments:
  -h, --help            show this help message and exit

INPUT FILES:
  Input files from the pangenome analysis.

  -p PAN_DB, --pan-db PAN_DB
                        Anvi'o pan database
  -g GENOMES_STORAGE, --genomes-storage GENOMES_STORAGE
                        Anvi'o genomes storage file

REPORTING:
  How do you want results to be reported? Anvi'o can produce a TAB-delimited
  output file for you (for which you would have to provide an output file
  name). Or the results can be stored in the pan database directly, for
  which you would have to explicitly ask for it. You can get both as well in
  case you are a fan of redundancy and poor data analysis practices. Anvi'o
  does not judge.

...

meren commented 3 years ago

OH you mean a link to the anvi'o help docs page, right?

Yes :) What you sent looks perfect :)

But I think it should be at the very end of the help menu rather than at the very beginning since it will improve usability and exposure of that info.

ekiefl commented 3 years ago

Feature added in https://github.com/merenlab/anvio/pull/1572

merenlab / anvio