Merge new doc in dev

.github/workflows/check_doc.yml

@@ -0,0 +1,25 @@
+name: Check documentation
+
+on:
+  push:
+    paths:
+      - 'docs/**'
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    # Standard drop-in approach that should work for most people.
+    - uses: ammaraskar/sphinx-action@master
+      with:
+        docs-folder: "docs/"
+        build-command: "sphinx-build -b html . build/"
+    # Great extra actions to compose with:
+    # Create an artifact of the html output.
+    - uses: actions/upload-artifact@v1
+      with:
+        name: DocumentationHTML
+        path: docs/build/

.github/workflows/check_recipes.yml

@@ -42,5 +42,5 @@ jobs:
         shell: bash -l {0}
         run: |
           cd testingDataset/
-          ppanggolin all --cpu 1 --anno organisms.gbff.list -o pango
+          ppanggolin all --cpu 1 --anno genomes.gbff.list -o pango
           ppanggolin info -p pango/pangenome.h5 --content --parameters --status

.github/workflows/main.yml

@@ -1,12 +1,11 @@
 name: CI
 
 on:
-  push:
-    branches: 
-      - '*'
   pull_request:
     branches: 
       - '*'
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
 
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
@@ -20,35 +19,38 @@ jobs:
         python-version: ['3.8', '3.9', '3.10']
     steps:
     # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-    - uses: actions/checkout@v2
-    # Setting up miniconda
+    - uses: actions/checkout@v3
+    # Install requirements with miniconda
     - uses: conda-incubator/setup-miniconda@v2
       with:
-        condarc-file: .condarc.yml
-        activate-environment: test
         python-version: ${{ matrix.python-version }}
-    # Install the dependencies
-    - name: Set up test environment
+        channels: conda-forge,bioconda,defaults
+        environment-file: ppanggolin_env.yaml
+        activate-environment: ppanggolin
+
+    - name: Install ppanggolin
       shell: bash -l {0}
       run: |
-        conda install -y --file requirements.txt 
         pip install .[test]
+
     # Check that it is installed and displays help without error
     - name: Check that PPanGGOLiN is installed
       shell: bash -l {0}
       run: |
         ppanggolin --version
         ppanggolin --help
+
     # Check that unit tests are all passing
     - name: Unit tests
       shell: bash -l {0}
       run: pytest
+
     # Test the complete workflow
     - name: Complete workflow
       shell: bash -l {0}
       run: |
         cd testingDataset
-        ppanggolin all --cpu 1 --fasta organisms.fasta.list --output mybasicpangenome
+        ppanggolin all --cpu 1 --fasta genomes.fasta.list --output mybasicpangenome
         ppanggolin info --pangenome mybasicpangenome/pangenome.h5 --content --parameters --status
         cd -
     # test most options calls. If there is a change in the API somewhere that was not taken into account (whether in the options for the users, or the classes for the devs), this should fail, otherwise everything is probably good.
@@ -57,7 +59,7 @@ jobs:
       shell: bash -l {0}
       run: |
         cd testingDataset
-        ppanggolin annotate --fasta organisms.fasta.list --output stepbystep --kingdom bacteria
+        ppanggolin annotate --fasta genomes.fasta.list --output stepbystep --kingdom bacteria
         ppanggolin cluster -p stepbystep/pangenome.h5 --coverage 0.8 --identity 0.8
         ppanggolin graph -p stepbystep/pangenome.h5 -r 10
         ppanggolin partition --output stepbystep -f -p stepbystep/pangenome.h5 --cpu 1 -b 2.6 -ms 10 -fd -ck 500 -Kmm 3 12 -im 0.04 --draw_ICL -se $RANDOM
@@ -67,25 +69,25 @@ jobs:
         ppanggolin spot -p stepbystep/pangenome.h5 --spot_graph --overlapping_match 2 --set_size 3 --exact_match_size 1
         ppanggolin draw -p stepbystep/pangenome.h5 --draw_spots -o stepbystep -f
         ppanggolin module -p stepbystep/pangenome.h5 --transitive 4 --size 3 --jaccard 0.86 --dup_margin 0.05
-        ppanggolin write_pangenome -p stepbystep/pangenome.h5 --output stepbystep -f --soft_core 0.9 --dup_margin 0.06  --gexf --light_gexf --csv --Rtab --stats --partitions --compress --json --spots --borders --families_tsv --cpu 1 
-        ppanggolin write_genomes  -p stepbystep/pangenome.h5 --output stepbystep -f --fasta organisms.fasta.list --gff --proksee --table
-        ppanggolin fasta -p stepbystep/pangenome.h5 --output stepbystep -f --prot_families all --gene_families shell --regions all --fasta organisms.fasta.list
+        ppanggolin write_pangenome -p stepbystep/pangenome.h5 --output stepbystep -f --soft_core 0.9 --dup_margin 0.06  --gexf --light_gexf --csv --Rtab --stats --partitions --compress --json --spots --regions --borders --families_tsv --cpu 1 
+        ppanggolin write_genomes  -p stepbystep/pangenome.h5 --output stepbystep -f --fasta genomes.fasta.list --gff --proksee --table
+        ppanggolin fasta -p stepbystep/pangenome.h5 --output stepbystep -f --prot_families all --gene_families shell --regions all --fasta genomes.fasta.list
         ppanggolin draw -p stepbystep/pangenome.h5 --draw_spots --spots all -o stepbystep -f
-        ppanggolin metrics -p stepbystep/pangenome.h5 --genome_fluidity --info_modules --no_print_info -f --log metrics.log
+        ppanggolin metrics -p stepbystep/pangenome.h5 --genome_fluidity --no_print_info --recompute_metrics --log metrics.log
         cd - 
     - name: gbff parsing and MSA computing
       shell: bash -l {0}
       run: |
         cd testingDataset
-        ppanggolin workflow --cpu 1 --anno organisms.gbff.list --output myannopang
+        ppanggolin workflow --cpu 1 --anno genomes.gbff.list --output myannopang
         ppanggolin msa --pangenome myannopang/pangenome.h5 --source dna --partition core -o myannopang/ -f --use_gene_id --phylo --single_copy
         cd -
     - name: clusters reading from external file
       shell: bash -l {0}
       run: |
         cd testingDataset
-        ppanggolin panrgp --anno organisms.gbff.list --cluster clusters.tsv --output readclusterpang
-        ppanggolin annotate --anno organisms.gbff.list --output readclusters
+        ppanggolin panrgp --anno genomes.gbff.list --cluster clusters.tsv --output readclusterpang
+        ppanggolin annotate --anno genomes.gbff.list --output readclusters
         ppanggolin cluster --clusters clusters.tsv -p readclusters/pangenome.h5
         ppanggolin msa --pangenome readclusterpang/pangenome.h5 --partition persistent --phylo -o readclusterpang/msa/ -f
         cd -
@@ -135,37 +137,40 @@ jobs:
       run: |
         cd testingDataset
         ppanggolin utils --default_config panrgp -o panrgp_default_config.yaml
-        ppanggolin panrgp  --anno organisms.gbff.list --cluster clusters.tsv -o test_config --config panrgp_default_config.yaml
+        ppanggolin panrgp  --anno genomes.gbff.list --cluster clusters.tsv -o test_config --config panrgp_default_config.yaml
         cd -
     - name: testing projection cmd
       shell: bash -l {0}
       run: |
         cd testingDataset
-        head organisms.gbff.list | sed 's/^/input_org_/g' > organisms.gbff.head.list
-        ppanggolin projection --pangenome stepbystep/pangenome.h5  -o projection_from_list_of_gbff --anno organisms.gbff.head.list --gff --proksee
+        head genomes.gbff.list | sed 's/^/input_genome_/g' > genomes.gbff.head.list
+        ppanggolin projection --pangenome stepbystep/pangenome.h5  -o projection_from_list_of_gbff --anno genomes.gbff.head.list --gff --proksee
 
 
         ppanggolin projection --pangenome mybasicpangenome/pangenome.h5  -o projection_from_single_fasta \
-                              --organism_name chlam_A --fasta FASTA/GCF_002776845.1_ASM277684v1_genomic.fna.gz \
+                              --genome_name chlam_A --fasta FASTA/GCF_002776845.1_ASM277684v1_genomic.fna.gz \
                               --spot_graph --graph_formats graphml --fast --keep_tmp -f --add_sequences --gff --proksee --table --add_metadata
 
+        ppanggolin projection --pangenome mybasicpangenome/pangenome.h5  -o projection_from_gff_prodigal \
+                              --genome_name chlam_annotated_with_prodigal --anno GBFF/GCF_003788785.1_ct114V1_genomic_prodigal_annotation.gff.gz \
+                               --gff  --table
 
     - name: testing write_genome_cmds
       shell: bash -l {0}
       run: |
         cd testingDataset
-        head organisms.gbff.list | cut -f1  > organisms_names.gbff.head.list
+        head genomes.gbff.list | cut -f1  > genome_names.gbff.head.list
 
-        ppanggolin write_genomes  -p myannopang/pangenome.h5 --output flat_genomes_from_file_org -f \
-                                  --anno organisms.gbff.list --gff --table --organisms  organisms_names.gbff.head.list 
+        ppanggolin write_genomes  -p myannopang/pangenome.h5 --output flat_genomes_from_genome_files -f \
+                                  --anno genomes.gbff.list --gff --table --genomes  genome_names.gbff.head.list 
 
-        ppanggolin write_genomes  -p stepbystep/pangenome.h5 --output flat_genomes_from_cmdline_orgs --proksee \
-                                --organisms GCF_006508185.1_ASM650818v1_genomic,GCF_002088315.1_ASM208831v1_genomic
+        ppanggolin write_genomes  -p stepbystep/pangenome.h5 --output flat_genomes_from_cmdline_genomes --proksee \
+                                --genomes GCF_006508185.1_ASM650818v1_genomic,GCF_002088315.1_ASM208831v1_genomic
 
-        head organisms.fasta.list | cut -f1  > organisms_names.fasta.head.list 
+        head genomes.fasta.list | cut -f1  > genome_names.fasta.head.list 
         # Default separator is a pipe but a pipe is found in a value of metadata db1. That is why we use another separator here. 
         ppanggolin write_genomes -p mybasicpangenome/pangenome.h5 --output mybasicpangenome/genomes_outputs \
-                                --organisms organisms_names.fasta.head.list \
+                                --genomes genome_names.fasta.head.list \
                                   -f --gff --add_metadata --table --metadata_sep § 
 
         # Pipe separatore is found in metadata source db1. if we don't require this source then the writting with pipe is work fine. 

docs/api/ppanggolin.formats.md

@@ -11,6 +11,15 @@
    :show-inheritance:
 ```
 
+## ppanggolin.formats.writeAnnotations module
+
+```{eval-rst}
+.. automodule:: ppanggolin.formats.writeAnnotations
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
 ## ppanggolin.formats.writeBinaries module
 
 ```{eval-rst}
@@ -56,6 +65,15 @@
    :show-inheritance:
 ```
 
+## ppanggolin.formats.write_proksee module
+
+```{eval-rst}
+.. automodule:: ppanggolin.formats.write_proksee
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
 ## Module contents
 
 ```{eval-rst}

docs/api/ppanggolin.md

@@ -1,5 +1,4 @@
-(ppanggolin-api)=
-# PPanGGOLiN Package
+# ppanggolin package
 
 ## Subpackages
 
@@ -19,6 +18,7 @@ ppanggolin.meta
 ppanggolin.metrics
 ppanggolin.mod
 ppanggolin.nem
+ppanggolin.projection
 ppanggolin.utility
 ppanggolin.workflow
 ```

docs/api/ppanggolin.projection.md

@@ -0,0 +1,21 @@
+# ppanggolin.projection package
+
+## Submodules
+
+## ppanggolin.projection.projection module
+
+```{eval-rst}
+.. automodule:: ppanggolin.projection.projection
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Module contents
+
+```{eval-rst}
+.. automodule:: ppanggolin.projection
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

docs/conf.py

@@ -36,6 +36,10 @@
     'sphinx_search.extension',
 ]
 
+# Prefix document path to section labels, to use:
+# `path/to/file:heading` instead of just `heading`
+autosectionlabel_prefix_document = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/dev/buildDoc.md

@@ -1,7 +1,7 @@
 # Build the documentation
 This partdescribe the guidelines to build the documentation of PPanGGOLiN.
 
-```{danger}
+```{warning}
 When you will merge or pull request your branch on master, a bot from readthedoc will see it and update the doc online.
 Be sure that your doc is clean and without error. 
 ```
@@ -16,20 +16,20 @@ readthedocs-sphinx-search==0.3.1
 sphinx-autobuild==2021.3.14
 myst-parser==1.0.0
 ```
-To build the doc you need to use an environment with panorama installed. 
+To build the doc you need to use an environnement with ppanggolin installed. 
 To make think easier [pyproject.toml file](../../pyproject.toml) contain the same list of requirement 
 and can install everything automatically with pip.
 ```shell
-# PANORAMA=/path/to/panorama/
-pip install $PANORAMA[doc]  # You can add -e to install in editable mode
+# PPanGGOLiN=/path/to/ppanggolin/
+pip install $PPanGGOLiN[doc]  # You can add -e to install in editable mode
 ```
 ## Build documentation with sphinx
 
 You can look at your modification in live by using **sphinx-autobuild** (installed previously).
 
 ```shell
-cd $PANORAMA/.docs
-sphinx-autobuild source/ build/
+cd $PPanGGOLiN/docs
+sphinx-autobuild . build/
 #copy server adresse, for me (as example) http://127.0.0.1:8000
 #paste the adresse in your browser
 ```
@@ -70,9 +70,9 @@ The API documentation is build automatically.
 To update the API documentation and keep the automatic update when a new package, module, submodules is added follow the
 next lines:
 ```shell
-sphinx-apidoc -o api $PANORAMA/panorama -f
+sphinx-apidoc -o api $PPanGGOLiN/ppanggolin -f
 ```
-```{attention}
+```{warning}
 *sphinx-apidoc* will generate ReStructeredText files. You need to convert them in markdown. For this follow the guides 
 [here](#rst2md)
 ```
@@ -113,14 +113,14 @@ sphinx-quickstart $DOCS
 #https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
 #> Project language [en]: 
 #
-#Creating file /home/jarnoux/Projects/PANORAMA/docs_scratch/source/conf.py.
-#Creating file /home/jarnoux/Projects/PANORAMA/docs_scratch/source/index.rst.
-#Creating file /home/jarnoux/Projects/PANORAMA/docs_scratch/Makefile.
-#Creating file /home/jarnoux/Projects/PANORAMA/docs_scratch/make.bat.
+#Creating file /your/path/PPanGGOLiN/docs_scratch/source/conf.py.
+#Creating file /your/path/Projects/PPanGGOLiN/docs_scratch/source/index.rst.
+#Creating file /your/path/Projects/PPanGGOLiN/docs_scratch/Makefile.
+#Creating file /your/path/Projects/PPanGGOLiN/docs_scratch/make.bat.
 #
 #Finished: An initial directory structure has been created.
 #
-#You should now populate your master file /home/jarnoux/Projects/PANORAMA/docs_scratch/source/index.rst and create other documentation
+#You should now populate your master file /home/jarnoux/Projects/PPanGGOLiN/docs_scratch/source/index.rst and create other documentation
 #source files. Use the Makefile to build the docs, like so:
 #   make builder
 #where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
@@ -205,7 +205,7 @@ For this case we will need to install a new package `rst-to-myst`.
 pip install rst-to-myst[sphinx]
 # Go to your environment with rst2myst
 rst2myst convert source/index.rst
-# Go back to your environment with panorama
+# Go back to your environment with ppanggolin
 rm source/index.rst
 ```
 #### README in index.md
@@ -224,7 +224,7 @@ The user documentation is completely handwritten. Moreover, we advise respecting
 1. One file per topic/command with an explicit text on the feature
 2. One file for the installation guidelines
 3. One file on how to report issue or enhancement
-4. Don't ref to any function in the panorama code. This is reserved for developper documentation
+4. Don't ref to any function in the ppanggolin code. This is reserved for developper documentation
 
 #### Developper documentation
 The developper documentation is handwritten too. We advise respecting the following guidelines:
@@ -238,13 +238,13 @@ The developper documentation is handwritten too. We advise respecting the follow
 #### API documentation
 To build the API documentation and use the docstring in code, you can use the command `sphinx-apidoc` as follows:
 ```shell
-sphinx-apidoc -o api $PANORAMA/panorama
+sphinx-apidoc -o api $PPanGGOLiN/ppanggolin
 # Go to your environment with rst2myst
 rst2myst convert api/*.rst
 # Go back to your environment with sphinx
 rm api/*.rst
 ```
-You have now documentation for PPanGGOLiN api. To ref api in your doc you can paste **\{ref\}\`package panorama\`**
+You have now documentation for PPanGGOLiN api. To ref api in your doc you can paste **\{ref\}\`package ppanggolin\`**
 
 ```{tip}
 With the "sphinx.ext.autosectionlabel", you will certainly get multiple warning for duplicate label.