Merge pull request #618 from macs3-project/doc/macs3/sphinx_migration

Doc/macs3/sphinx migration -> test_peak_overlap

.github/workflows/build-and-test-MACS3-website.yml

@@ -1,42 +1,38 @@
-# This workflow will install Python dependencies, run tests and lint with a single version of Python
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
-
-name: MACS3 website using Jekyll
+name: Build and Test MACS3 website using Sphinx
 
 on: 
-  push:
-    paths:
+  push: 
+    paths: 
       - 'docs/**'
       - '**.md'
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
 
 jobs:
-  build:
-    runs-on: ubuntu-20.04
-    strategy: 
-      matrix: 
-        python-version: [3.12]
-        arch: ['x64']
-    name: Build MACS3 website on x64 with Python ${{ matrix.python-version }}
+  build-and-publish:
+    runs-on: ubuntu-latest
     steps:
-      - name: Checkout MACS
-        uses: actions/checkout@v4
-        #with: # we don't need submodules for building docs
-        #  submodules: 'true'
-      - name: Copy md and images over
-        run: |
-          mkdir site_source
-          cp -r docs/ site_source/
-          cp *.md site_source/
-          cp _config.yml site_source/
-          cp -r _layouts/ site_source/
-      - name: Setup Pages
-        uses: actions/configure-pages@v3
-      - name: Build Website
-        uses: actions/jekyll-build-pages@v1
-        with:
-          source: "./site_source"
-          destination: "./site_output"
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v1
-        with:
-          path: "./site_output"
+    - uses: actions/checkout@v4  # Checks-out your repository under $GITHUB_WORKSPACE
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'  # Set up the Python version you need
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install sphinx myst-parser  # Add other dependencies you might have
+
+    - name: Build Sphinx Documentation
+      run: |
+        cd docs  # Change to your documentation directory if needed
+        make html
+        cd ..
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        # Upload entire repository
+        path: './docs/build/html'
+

.github/workflows/publish-to-gh-with-sphinx.yml

@@ -0,0 +1,56 @@
+name: Build and Publish Sphinx Documentation
+
+on:
+  push:
+    branches: ["master"]
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4  # Checks-out your repository under $GITHUB_WORKSPACE
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'  # Set up the Python version you need
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install sphinx myst-parser  # Add other dependencies you might have
+
+    - name: Build Sphinx Documentation
+      run: |
+        cd docs  # Change to your documentation directory if needed
+        make html
+        cd ..
+
+    - name: Setup Pages
+      uses: actions/configure-pages@v4
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        # Upload entire repository
+        path: './docs/build/html'
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4
+

.gitignore

@@ -113,7 +113,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/build/
 
 # PyBuilder
 target/

README.md

@@ -27,7 +27,30 @@ applied to any "DNA enrichment assays" if the question to be asked is
 simply: *where we can find significant reads coverage than the random
 background*.
 
-##  Changes for MACS (3.0.0)
+## Changes for MACS (3.0.1)
+
+*Bugs fixed*
+
+1) Fixed a bug that the `hmmatac` can't correctly save the
+	digested signal files. #605 #611
+
+2) Applied a patch to remove cython requirement from the installed
+	system. (it's needed for building the package). #606 #612
+
+3) Relax the testing script while comparing the peaks called from
+	current codes and the standard peaks. #615. To implement this, we
+	added 'intersection' function to 'Regions' class to find the
+	intersecting regions of two Regions object (similar to PeakIO but
+	only recording chromosome, start and end positions). And we
+	updated the unit test 'test_Region.py' then implemented a script
+	'jaccard.py' to compute the Jaccard Index of two peak files. If
+	the JI > 0.99 we would think the peaks called and the standard
+	peaks are similar. This is to avoid the problem caused by
+	different Numpy libraries, when the certain peak coordinates may
+	have 1bp difference.
+
+
+## Changes for MACS (3.0.0)
 
 1) Call variants in peak regions directly from BAM files. The
 	function was originally developed under code name SAPPER. Now
@@ -105,7 +128,7 @@ background*.
 The common way to install MACS is through
 [PYPI](https://pypi.org/project/macs3/)) or
 [conda](https://anaconda.org/macs3/macs3). Please check the
-[INSTALL](./docs/INSTALL.md) document for detail.
+[INSTALL](docs/INSTALL.md) document for detail.
 
 MACS3 has been tested using GitHub Actions for every push and PR in
 the following architectures:
@@ -144,30 +167,30 @@ of the subcommands.
 
 Subcommand | Description
 -----------|----------
-[`callpeak`](./docs/callpeak.md) | Main MACS3 Function to call peaks from alignment results.
-[`bdgpeakcall`](./docs/bdgpeakcall.md) | Call peaks from bedGraph file.
-[`bdgbroadcall`](./docs/bdgbroadcall.md) | Call nested broad peaks from bedGraph file.
-[`bdgcmp`](./docs/bdgcmp.md) | Comparing two signal tracks in bedGraph format.
-[`bdgopt`](./docs/bdgopt.md) | Operate the score column of bedGraph file.
-[`cmbreps`](./docs/cmbreps.md) | Combine bedGraph files of scores from replicates.
-[`bdgdiff`](./docs/bdgdiff.md) | Differential peak detection based on paired four bedGraph files.
-[`filterdup`](./docs/filterdup.md) | Remove duplicate reads, then save in BED/BEDPE format file.
-[`predictd`](./docs/predictd.md) | Predict d or fragment size from alignment results. In case of PE data, report the average insertion/fragment size from all pairs.
-[`pileup`](./docs/pileup.md) | Pileup aligned reads (single-end) or fragments (paired-end)
-[`randsample`](./docs/randsample.md) | Randomly choose a number/percentage of total reads, then save in BED/BEDPE format file.
-[`refinepeak`](./docs/refinepeak.md) | Take raw reads alignment, refine peak summits.
-[`callvar`](./docs/callvar.md) | Call variants in given peak regions from the alignment BAM files.
-[`hmmratac`](./docs/hmmratac.md) | Dedicated peak calling based on Hidden Markov Model for ATAC-seq data.
+[`callpeak`](docs/callpeak.md) | Main MACS3 Function to call peaks from alignment results.
+[`bdgpeakcall`](docs/bdgpeakcall.md) | Call peaks from bedGraph file.
+[`bdgbroadcall`](docs/bdgbroadcall.md) | Call nested broad peaks from bedGraph file.
+[`bdgcmp`](docs/bdgcmp.md) | Comparing two signal tracks in bedGraph format.
+[`bdgopt`](docs/bdgopt.md) | Operate the score column of bedGraph file.
+[`cmbreps`](docs/cmbreps.md) | Combine bedGraph files of scores from replicates.
+[`bdgdiff`](docs/bdgdiff.md) | Differential peak detection based on paired four bedGraph files.
+[`filterdup`](docs/filterdup.md) | Remove duplicate reads, then save in BED/BEDPE format file.
+[`predictd`](docs/predictd.md) | Predict d or fragment size from alignment results. In case of PE data, report the average insertion/fragment size from all pairs.
+[`pileup`](docs/pileup.md) | Pileup aligned reads (single-end) or fragments (paired-end)
+[`randsample`](docs/randsample.md) | Randomly choose a number/percentage of total reads, then save in BED/BEDPE format file.
+[`refinepeak`](docs/refinepeak.md) | Take raw reads alignment, refine peak summits.
+[`callvar`](docs/callvar.md) | Call variants in given peak regions from the alignment BAM files.
+[`hmmratac`](docs/hmmratac.md) | Dedicated peak calling based on Hidden Markov Model for ATAC-seq data.
 
 For advanced usage, for example, to run `macs3` in a modular way,
-please read the [advanced usage](./docs/Advanced_Step-by-step_Peak_Calling.md). There is a
-[Q&A](./docs/qa.md) document where we collected some common questions
+please read the [advanced usage](docs/Advanced_Step-by-step_Peak_Calling.md). There is a
+[Q&A](docs/qa.md) document where we collected some common questions
 from users.
 
 ## Contribute
 
-Please read our [CODE OF CONDUCT](./CODE_OF_CONDUCT.md) and [How to
-contribute](./CONTRIBUTING.md) documents. If you have any questions,
+Please read our [CODE OF CONDUCT](CODE_OF_CONDUCT.md) and [How to
+contribute](CONTRIBUTING.md) documents. If you have any questions,
 suggestion/ideas, or just want to have conversions with developers and
 other users in the community, we recommend using the [MACS
 Discussions](https://github.com/macs3-project/MACS/discussions)
@@ -193,3 +216,15 @@ contributions over the years.
  * [UCSC toolkits](http://hgdownload.cse.ucsc.edu/admin/exe/)
  * [deepTools](https://github.com/deeptools/deepTools/)
 
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+docs/INSTALL.md
+docs/index.md
+docs/Advanced_Step-by-step_Peak_Calling.md
+docs/qa.md
+docs/tutorial.md
+CODE_OF_CONDUCT.md
+CONTRIBUTING.md

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/callvar.md

@@ -123,7 +123,7 @@ will be stored in a BAM file.
 
 ## `callvar` Algorithm
 
-![Callvar Algorithm](./callvar_algorithm.jpeg)
+![Callvar Algorithm](callvar_algorithm.jpeg)
 
 Functional sequencing assays which targeted at particular sequences,
 such as ChIP-Seq, were thought to be unsuitable for *de novo*

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/pileup.md

@@ -12,7 +12,7 @@ The `pileup` command takes in one or multiple input files and produces
 an output file with the piled-up genomic coverage. It uses an
 efficient algorithm to pile up the alignments.
 
-![Pileup Algorithm](./pileup.png)
+![Pileup Algorithm](pileup.png)
 
 Pileup aligned reads with a given extension size (fragment size or d
 in MACS language). Note there will be no step for duplicate reads

docs/qa.md

@@ -0,0 +1 @@
+# Common Q & A

docs/source/CODE_OF_CONDUCT.md

@@ -0,0 +1 @@
+../../CODE_OF_CONDUCT.md

docs/source/CONTRIBUTING.md

@@ -0,0 +1 @@
+../../CONTRIBUTING.md

docs/source/conf.py

@@ -0,0 +1,41 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'MACS3'
+copyright = '2024, Tao Liu, Philippa Doherty'
+author = 'Tao Liu, Philippa Doherty'
+release = '3.0.1'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'myst_parser',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.githubpages'
+    ]
+
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+html_theme = "sphinx_rtd_theme"
+html_static_path = ['_static']

docs/source/docs/Advanced_Step-by-step_Peak_Calling.md

@@ -0,0 +1 @@
+../../../docs/Advanced_Step-by-step_Peak_Calling.md

docs/source/docs/INSTALL.md

@@ -0,0 +1 @@
+../../../docs/INSTALL.md

docs/source/docs/bdgbroadcall.md

@@ -0,0 +1 @@
+../../../docs/bdgbroadcall.md

docs/source/docs/bdgcmp.md

@@ -0,0 +1 @@
+../../../docs/bdgcmp.md

docs/source/docs/bdgdiff.md

@@ -0,0 +1 @@
+../../../docs/bdgdiff.md

docs/source/docs/bdgopt.md

@@ -0,0 +1 @@
+../../../docs/bdgopt.md

docs/source/docs/bdgpeakcall.md

@@ -0,0 +1 @@
+../../../docs/bdgpeakcall.md

docs/source/docs/callpeak.md

@@ -0,0 +1 @@
+../../../docs/callpeak.md

docs/source/docs/callvar.md

@@ -0,0 +1 @@
+../../../docs/callvar.md