Migrate OSF docs to MkDocs and add GitHub Pages deploy

.github/workflows/docs.yml

@@ -0,0 +1,62 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "mkdocs_hooks.py"
+      - "tools/mirror_osf_wiki.py"
+      - "tools/promote_osf_wiki_to_docs.py"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material pymdown-extensions
+
+      - name: Build docs
+        run: mkdocs build --strict
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -34,8 +34,9 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+site/
 
 
 # test output
 tests/input/*/output/*
-sigProfilerPlotting/examples/output/
+sigProfilerPlotting/examples/output/

README.md

@@ -1,11 +1,11 @@
-[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://osf.io/2aj6t/wiki/home/) [![License](https://img.shields.io/badge/License-BSD\%202--Clause-orange.svg)](https://opensource.org/licenses/BSD-2-Clause) [![CI](https://github.com/sigprofilersuite/SigProfilerPlotting/actions/workflows/ci.yml/badge.svg)](https://github.com/sigprofilersuite/SigProfilerPlotting/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://sigprofilersuite.github.io/SigProfilerPlotting/) [![License](https://img.shields.io/badge/License-BSD\%202--Clause-orange.svg)](https://opensource.org/licenses/BSD-2-Clause) [![CI](https://github.com/sigprofilersuite/SigProfilerPlotting/actions/workflows/ci.yml/badge.svg)](https://github.com/sigprofilersuite/SigProfilerPlotting/actions/workflows/ci.yml)
 
 # SigProfilerPlotting
 SigProfilerPlotting provides a standard tool for displaying all types of mutational signatures as well as all types of mutational patterns in cancer genomes. The tool seamlessly integrates with other SigProfiler tools.
 
 **INTRODUCTION**
 
-The purpose of this document is to provide a guide for using the SigProfilerPlotting framework and associated functions/tools to visualize the output from SigProfilerExtraction and SigProfilerSimulator. An extensive Wiki page detailing the usage of this tool can be found at https://osf.io/2aj6t/wiki/home.
+The purpose of this document is to provide a guide for using the SigProfilerPlotting framework and associated functions/tools to visualize the output from SigProfilerExtraction and SigProfilerSimulator. The primary documentation is now maintained in this repository under `docs/`, and the legacy OSF wiki source is at https://osf.io/2aj6t/wiki/home.
 
 For users that prefer working in an R environment, a wrapper package is provided and can be found and installed from: https://github.com/AlexandrovLab/SigProfilerPlottingR
 

docs/Example-Program.md

@@ -0,0 +1,25 @@
+## Running the Example Program ##
+After you have successfully installed SigProfilerPlotting, [download SigProfilerPlottingExampleProgram.zip][1], and move it to your desktop and unzip it.
+
+Next, open up your application terminal and enter the following command:
+
+    cd ~/Desktop/SigProfilerPlottingExampleProgram/
+
+You can now run the example program by entering the command:
+
+    python3 plot_example.py
+
+It may take a few seconds to complete. You can find the output graphs in the directory labeled `plots`, which is located in your current directory. If you are having difficulty locating the folder, open the finder application and press `⌘ + Shift + G` and enter into the "Go to the Folder" drop down menu: `~/Desktop/SigProfilerPlottingExampleProgram/plots/`
+
+ @[osf](kw8py)
+
+If you delete the four plot files and run plot_example.py then they should be generated again.
+<br>
+<br>
+Now that you were able to run `plot_example.py` your environment is set up and you are ready to start writing your own applications. Take a look at the sections labeled [Plotting Substitutions][2], [Plotting Indels][3], and [Plotting Dinucleotides][4] for more details about the different functions that SigProfilerPlotting provides.
+
+
+  [1]: https://osf.io/2wh7g/
+  [2]: https://osf.io/2aj6t/wiki/3.%20Plotting%20Substitutions/
+  [3]: https://osf.io/2aj6t/wiki/4.%20Plotting%20Indels/
+  [4]: https://osf.io/2aj6t/wiki/5.%20Plotting%20Dinucleotides/

docs/Installation-Python.md

@@ -0,0 +1,100 @@
+<h1>SigProfilerPlotting Installation Guide</h1>
+
+----------
+
+## Prerequisites ##
+
+SigProfilerPlotting requires that you have:
+<ul>
+    <li>Internet Connection</li>
+    <li>Python version 3.4.0 or newer</li>
+    <li>SigProfilerMatrixGenerator (recommended)</li>
+</ul>
+
+## Mac/Unix ##
+Check that you have the required python version by opening Terminal (`⌘ + Space` type `terminal` and hit `return` to open the application) and entering the command:
+
+    python3 --version
+
+You should see an output similar to:
+
+    ~ python3 --version
+    Python 3.4.0
+
+If you do not get a similar output (or a version that is 3.4.0 or newer), you will need to [install python3][1] before continuing with this guide.
+
+Next you will want to make sure that you have `pip3` installed because it will be used for importing sigProfilerPlotting. Check that you have `pip3` installed by entering into terminal:
+
+    pip3 --version
+
+You should see an output similar to: 
+
+    ~ pip3 --version
+    pip 19.0.1 /Library/Frameworks/SomeFilePath/
+
+If you do not have pip3 installed, then follow [homebrew's guide][2] for installing pip.
+
+
+Next, use pip3 to download SigProfilerPlotting.
+
+    pip3 install sigProfilerPlotting
+
+You can check that the installation was successful by entering into Terminal:
+
+    pip3 list
+This command will output a list of libraries that you have access to. Matplotlib and sigProfilerPlotting should be two of the libraries listed.
+
+@[osf](uabr5)
+
+If the download fails or you receive an error, check to make sure that python3 and pip3 are installed by using the --version commands. If they are not, start from the beginning of the guide and follow the directions again to download them.
+
+## Windows ##
+First, start by opening up Command Prompt. Navigate to the search bar in the lower left hand corner of the screen and search `cmd` and open the application `Command Prompt`.
+
+Next, you will download and install Python and Pip. Check if Python is installed by entering the command:
+
+    python --version
+
+If you have Python installed, you should receive an output similar to:
+
+    C:\Users\YourUserName>python
+    Python 3.7.3 (v3.7.3:ef4ec6ed12, Mar 25 2019, 22:22:05) [MSC v.1916 64 bit (AMD64)] on win32
+    Type "help", "copyright", "credits" or "license" for more information.
+    >>>
+
+If you do not have python, or need Python 3.4.0 or newer, then [download Python here][3].
+
+After downloading and installing Python, fill in your username at `YourUsernameHere` and run: 
+
+    setx PATH “%PATH%;C:\Users\YourUsernameHere\AppData\Local\Programs\Python\Python37\”
+    setx PATH “%PATH%;C:\Users\YourUsernameHere\AppData\Local\Programs\Python\Python37\Scripts\”
+
+This will set the path so that you can call Python and pip from the command line.
+
+Check that you have the required libraries installed by entering into the command line:
+
+    python --version
+    pip --version
+
+If you both commands output version numbers, then you have successfully downloaded and installed Python and pip and you are ready to proceed. Otherwise, go through the process of reinstalling Python and pip.
+
+Now that your environment is ready, use pip to install sigProfilerPlotting.
+
+    pip install sigProfilerPlotting
+
+If the download was successful, then sigProfilerPlotting should be one of the libraries outputted by the following command.
+
+    pip list
+
+@[osf](egk7c)
+
+Now your environment should be setup and ready to use the sigProfilerPlotting library.
+
+If you are receiving an error, check to make sure that python and pip are installed by using the --version commands. If they are not installed, start from the beginning of the guide and follow the directions again to download them.
+
+**Note for Windows Users**: When passing the path to your files as a parameter to any of the functions, you will need make your string into a raw string literal (ie. the String "C:\User\YourUserName\Desktop\\" will need to be r"C:\User\YourUserName\Desktop\\\\").
+
+
+  [1]: https://realpython.com/installing-python/
+  [2]: https://docs.brew.sh/Homebrew-and-Python
+  [3]: https://www.python.org/

docs/Installation-R.md

@@ -0,0 +1,75 @@
+<h1>SigProfilerPlotting Installation (R-wrapper) Guide</h1>
+
+----------
+
+## Prerequisites ##
+
+SigProfilerPlottingR requires that you have:
+<ul>
+    <li>Internet Connection</li>
+    <li>Python version 3.4.0 or newer</li>
+    <li>SigProfilerMatrixGeneratorR (recommended)</li>
+</ul>
+
+## Mac/Unix ##
+Check that you have the required python version by opening Terminal (`⌘ + Space` type `terminal` and hit `return` to open the application) and entering the command:
+
+    python3 --version
+
+You should see an output similar to:
+
+    ~ python3 --version
+    Python 3.4.0
+
+If you do not get a similar output (or a version that is 3.4.0 or newer), you will need to [install python3][1] before continuing with this guide.
+
+Next you will want to make sure that you have `pip3` installed because it will be used for importing sigProfilerPlotting. Check that you have `pip3` installed by entering into terminal:
+
+    pip3 --version
+
+You should see an output similar to: 
+
+    ~ pip3 --version
+    pip 19.0.1 /Library/Frameworks/SomeFilePath/
+
+If you do not have pip3 installed, then follow [homebrew's guide][2] for installing pip.
+
+
+Next, use pip3 to download SigProfilerPlotting.
+
+    pip3 install sigProfilerPlotting
+
+You can check that the installation was successful by entering into Terminal:
+
+    pip3 list
+This command will output a list of libraries that you have access to. Matplotlib and sigProfilerPlotting should be two of the libraries listed.
+
+@[osf](uabr5)
+
+If the download fails or you receive an error, check to make sure that python3 and pip3 are installed by using the --version commands. If they are not, start from the beginning of the guide and follow the directions again to download them.
+
+## Installing R dependencies ##
+You must install the devtools and reticulate libraries:
+
+    $ R
+    >> install.packages("devtools")
+    >> install.packages("reticulate") 
+
+Now you are ready to install SigProfilerPlottingR:
+
+    $ R
+    >> library("reticulate")
+    >> use_python("path_to_your_python3")
+    >> py_config()
+    >> library("devtools")
+    >> install_github("AlexandrovLab/SigProfilerPlottingR")
+
+Ensure that you can properly load the package:
+
+    >> library("SigProfilerPlottingR")
+
+
+
+  [1]: https://realpython.com/installing-python/
+  [2]: https://docs.brew.sh/Homebrew-and-Python
+  [3]: https://www.python.org/

docs/Plotting-Dinucleotides.md

@@ -0,0 +1,69 @@
+# Plotting Dinucleotides #
+
+----------
+
+Refer to this page to learn about how to plot dinucleotides (DBS) using the plotDBS function. Included below is the function and a list of valid parameter values. There are also examples of each DBS graph with a quick description for interpreting it. 
+
+@[toc](Sections)
+
+## plotDBS Function ##
+Plots the number of double base substitutions.
+
+    plotDBS(matrix_path, output_path, project, plot_type, percentage=False, custom_text_upper=None, custom_text_middle=None, custom_text_lower=None)
+
+For those using the R-wrapper, you must switch any "True" to "TRUE", "False" to "FALSE", and "None" to "NULL."
+
+- **matrix_path** -> (String) The path to your matrix (generated by SigProfilerMatrixGenerator).<br>
+- **output_path** -> (String) The path to where the output will be saved.<br>
+- **project** -> (String) The output file will have this value postfixed in the name.<br>
+- **plot type** -> (String) The plot type to be generated. Valid inputs include {"78", "312"}.<br>
+- **percentage** -> (Boolean) True for a normalized percentile plot and False for a numerical plot. This parameter has a default value of False.<br>
+- **custom_text_upper, custom_text_middle, custom_text_bottom** -> (List of Strings) Provide a list of strings for adding a custom text to the upper right-hand corner of the plot. Ideally, there should be one string per sample. Extra strings will not be plotted. The three parameters allow for three rows of custom text (upper, middle, lower).
+
+Supported SigProfiler Matrices include: 78 and 186.<br>
+
+## plotDBS Examples ##
+The following examples were generated in a python environment where sigProfilerPlotting was imported as sigPlt.
+
+    $ python3
+    >>import sigProfilerPlotting as sigPlt
+
+From within a R session:
+
+    $ R
+    >> library("reticulate")
+    >> use_python("path_to_your_python3")
+    >> py_config()
+    >> library("SigProfilerPlottingR")
+
+The matrices below are used to generate the example plots. You can download and run the commands to generate the example plots.
+- [DBS-78][1]
+- [DBS-186][2]
+
+### Plot DBS-78 ###
+From within a Python session:
+
+    sigPlt.plotDBS(matrix_path_DINUC + "DBS78.all", output_path, project_name, "78", percentage=False)
+
+From within a R session:
+
+    plotDBS(matrix_path_DINUC + "DBS78.all", output_path, project_name, "78", percentage=FALSE)
+
+@[osf](s7wuj)
+The **Double Base Substitution-78 (DBS-78) plot** counts the number of double base mutations. The DBS categories are listed along the top of the plot, and the number of each mutation are represented along the y-axis. The 78 mutational channels are determined using the maximum pyrimidine context of the mutation.
+
+### Plot DBS-186 ###
+From within a Python session:
+
+    sigPlt.plotDBS(matrix_path_DINUC + "DBS186.all", output_path, project_name, "186",False)
+
+From within a R session:
+
+    plotDBS(matrix_path_DINUC + "DBS186.all", output_path, project_name, "186",FALSE)
+
+@[osf](uxyfv)
+The **Double Base Substitution-186 (DBS-186) plot** counts the number of double base mutations that occur on the transcribed or untranscribed strands within protein coding regions. Only doublet-substitutions containing all pyrimidines or all purines can be classified this way. The DBS categories are listed along the top of the plot, and the number of each mutation are represented along the y-axis.
+
+
+  [1]: https://osf.io/d3e6f/
+  [2]: https://osf.io/p2fxv/