mv from readthedocs to mkdocs

NBISweden · Sep 3, 2024 · eb7209e · eb7209e
1 parent 69a4ebb
commit eb7209e
Show file tree

Hide file tree

Showing 88 changed files with 541 additions and 421 deletions.
diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml
@@ -0,0 +1,32 @@
+name: ci
+on:
+  push:   
+    paths:
+      - 'docs/**'
+      - mkdocs.yml
+  pull_request:
+    paths:
+      - 'docs/**'
+      - mkdocs.yml
+
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - uses: actions/cache@v2
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - run: pip install mkdocs-material
+      - run: pip install pymdown-extensions
+      - run: pip install mkdocs-minify-plugin
+      - run: pip install mkdocs-macros-plugin
+      - run: pip install mkdocs-embed-external-markdown
+      - run: pip install mkdocs-table-reader-plugin
+      - run: mkdocs gh-deploy --force
diff --git a/.readthedocs.yml b/.readthedocs.yml
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,52 @@
+### Mkdocs
+
+#### Welcome to MkDocs
+
+For full documentation visit [mkdocs.org](https://www.mkdocs.org).  
+For full documentation about the [material mkdocs theme](https://squidfunk.github.io/mkdocs-material/).
+
+#### Installation
+
+##### Manual
+
+As prerequisite you need python >=3.8 and pip.  
+
+Install Mkdocs:
+
+`pip install mkdocs`
+
+For the theme:  
+`pip install mkdocs-material`
+
+For the extensions:  
+`pip install pymdown-extensions`
+
+For the plugins:  
+`pip install mkdocs-minify-plugin`  
+`pip install mkdocs-macros-plugin`
+`pip install mkdocs-embed-external-markdown`
+
+##### Conda
+
+Clone the repository and move in it.  
+Then install all dependencies using conda and the `conda_env.yml` shipped with this repo:
+
+```
+conda env create -f conda_env.yml
+```
+
+Activate the environment and you are good:
+
+```
+conda activate education
+```
+
+#### Testing and building the website
+
+
+* `mkdocs serve` - Start the live-reloading docs server, to test the site locally (http://127.0.0.1:8000/).
+* `mkdocs gh-deploy` - Deploys the site on github pages.
+
+* `mkdocs build` - Build the documentation site.
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs -h` - Print help message and exit.
diff --git a/docs/how_to_cite.md b/docs/how_to_cite.md
@@ -1,4 +1,4 @@
-## How to cite?
+# How to cite?
 
 This work has not been published yet(I will think about it). But if you wish to cite AGAT you can do it as follow (Adapt the version for the one you have used): 
 

diff --git a/docs/img/aggregate_annotations.png b/docs/img/aggregate_annotations.png
diff --git a/docs/img/aggregate_annotations.pptx b/docs/img/aggregate_annotations.pptx
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,16 @@
+Welcome to AGAT's documentation!
+================================
+
+AGAT: Another GTF/GFF Analysis Toolkit
+----------------------------------------
+
+**A GFF/GTF toolkit allowing you to perform almost everything you might want to achieve ^^**
+
+The GTF/GFF formats are 9-column text formats used to describe and represent genomic features.
+The formats have quite evolved since 1997, and despite well-defined specifications existing nowadays they have a great flexibility allowing holding wide variety of information.
+This flexibility has a drawback aspect, there is an incredible amount of flavor of the formats: GFF / GFF1 / GFF2 / GFF2.5 / GFF3 / GTF / GTF2 / GTF2.1 / GTF2.2 / GTF2.5 / GTF3
+
+It's often hard to understand and differentiate all GFF/GTF formats/flavors. Many tools using GTF/GFF formats fails due to specific expectations.
+AGAT is a suite of tools able to deal with any GTF/GFF formats and perform most of the possible tasks you would need.
+
+![](img/wordcloud.png){ width=600px }
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/tools/agat_convert_bed2gff.md b/docs/tools/agat_convert_bed2gff.md
@@ -1,11 +1,11 @@
-# agat\_convert\_bed2gff.pl
+# agat_convert_bed2gff.pl
 
 ## DESCRIPTION
 
 The script takes a bed file as input, and will translate it in gff format.
 The BED format is described [here](https://genome.ucsc.edu/FAQ/FAQformat.html##format1)
-The script converts 0-based, half-open \[start-1, end) bed file to
-1-based, closed \[start, end\] General Feature Format v3 (GFF3).
+The script converts 0-based, half-open [start-1, end) bed file to
+1-based, closed [start, end] General Feature Format v3 (GFF3).
 
 ## SYNOPSIS
 
@@ -23,23 +23,23 @@ agat_convert_bed2gff.pl -h
 - **--source**
 
     The source informs about the tool used to produce the data and is stored in 2nd field of a gff file.
-    Example: Stringtie,Maker,Augustus,etc. \[default: data\]
+    Example: Stringtie,Maker,Augustus,etc. [default: data]
 
-- **--primary\_tag**
+- **--primary_tag**
 
-    The primary\_tag corresponds to the data type and is stored in 3rd field of a gff file.
-    Example: gene,mRNA,CDS,etc.  \[default: gene\]
+    The primary_tag corresponds to the data type and is stored in 3rd field of a gff file.
+    Example: gene,mRNA,CDS,etc.  [default: gene]
 
-- **--inflate\_off**
+- **--inflate_off**
 
     By default we inflate the block fields (blockCount, blockSizes, blockStarts) to create subfeatures
-    of the main feature (primary\_tag). The type of subfeature created is based on the
-    inflate\_type parameter. If you do not want this inflating behaviour you can deactivate it
-    by using the --inflate\_off option.
+    of the main feature (primary_tag). The type of subfeature created is based on the
+    inflate_type parameter. If you do not want this inflating behaviour you can deactivate it
+    by using the --inflate_off option.
 
-- **--inflate\_type**
+- **--inflate_type**
 
-    Feature type (3rd column in gff) created when inflate parameter activated \[default: exon\].
+    Feature type (3rd column in gff) created when inflate parameter activated [default: exon].
 
 - **--verbose**
 

diff --git a/docs/tools/agat_convert_embl2gff.md b/docs/tools/agat_convert_embl2gff.md
@@ -1,4 +1,4 @@
-# agat\_convert\_embl2gff.pl
+# agat_convert_embl2gff.pl
 
 ## DESCRIPTION
 
@@ -22,7 +22,7 @@ agat_converter_embl2gff.pl --embl infile.embl [ -o outfile ]
     This is an EMBL format dedicated for submission and contains particularity to deal with.
     This parameter is needed to get a proper sequence id in the GFF3 from an embl made with EMBLmyGFF3.
 
-- **--primary\_tag**, **--pt**, **-t**
+- **--primary_tag**, **--pt**, **-t**
 
     List of "primary tag". Useful to discard or keep specific features.
     Multiple tags must be coma-separated.

diff --git a/docs/tools/agat_convert_genscan2gff.md b/docs/tools/agat_convert_genscan2gff.md
@@ -1,18 +1,18 @@
-# agat\_convert\_genscan2gff.pl
+# agat_convert_genscan2gff.pl
 
 ## DESCRIPTION
 
 The script takes a genscan file as input, and will translate it in gff format.
-The genscan format is described here: http://genome.crg.es/courses/Bioinformatics2003\_genefinding/results/genscan.html
-/!\\ vvv Known problem vvv /!\\
+The genscan format is described here: http://genome.crg.es/courses/Bioinformatics2003_genefinding/results/genscan.html
+/! vvv Known problem vvv /!
 You must have submited only DNA sequence, wihtout any header!!
 Indeed the tool expects only DNA sequences and does not crash/warn if an header
 is submited along the sequence.
 e.g If you have an header ">seq" s-e-q are seen as the 3 first nucleotides of the sequence.
 Then all prediction location are shifted accordingly.
 (checked only on the online version http://argonaute.mit.edu/GENSCAN.html. I don't
 know if there is the same pronlem elsewhere.)
-/!\\ ^^^ Known problem ^^^^ /!\\
+/! ^^^ Known problem ^^^^ /!
 
 ## SYNOPSIS
 
@@ -30,12 +30,12 @@ agat_convert_genscan2gff.pl -h
 - **--source**
 
     The source informs about the tool used to produce the data and is stored in 2nd field of a gff file.
-    Example: Stringtie,Maker,Augustus,etc. \[default: data\]
+    Example: Stringtie,Maker,Augustus,etc. [default: data]
 
-- **--primary\_tag**
+- **--primary_tag**
 
-    The primary\_tag corresponf to the data type and is stored in 3rd field of a gff file.
-    Example: gene,mRNA,CDS,etc.  \[default: gene\]
+    The primary_tag corresponf to the data type and is stored in 3rd field of a gff file.
+    Example: gene,mRNA,CDS,etc.  [default: gene]
 
 - **--verbose**
 

diff --git a/docs/tools/agat_convert_mfannot2gff.md b/docs/tools/agat_convert_mfannot2gff.md
@@ -1,4 +1,4 @@
-# agat\_convert\_mfannot2gff.pl
+# agat_convert_mfannot2gff.pl
 
 ## DESCRIPTION
 

diff --git a/docs/tools/agat_convert_minimap2_bam2gff.md b/docs/tools/agat_convert_minimap2_bam2gff.md
@@ -1,11 +1,11 @@
-# agat\_convert\_minimap2\_bam2gff.pl
+# agat_convert_minimap2_bam2gff.pl
 
 ## DESCRIPTION
 
 The script converts output from minimap2 (bam or sam) into GFF file.
 To get bam from minimap2 use the following command:  
 
-minimap2 -ax splice:hq genome.fa Asecodes\_parviclava.nucest.fa | samtools sort -O BAM -o output.bam  
+minimap2 -ax splice:hq genome.fa Asecodes_parviclava.nucest.fa | samtools sort -O BAM -o output.bam  
 
 To use bam with this script you will need samtools in your path.