doc: improve docstrings, theme and rst

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: Check
+name: Test & Doc
 
 on:
   push:
@@ -8,7 +8,7 @@ on:
 
 permissions:
   contents: write
-    
+
 jobs:
 
   Test:
@@ -18,11 +18,8 @@ jobs:
         python-version: [ "3.8", "3.9", "3.10", "3.11", "3.12" ]
         include:
           - os: ubuntu-latest
-            python-version: "3.12"
           # - os: windows-latest
-          #   python-version: "3.12"
           - os: macos-latest
-            python-version: "3.12"
 
     runs-on: ${{ matrix.os }}
     steps:
@@ -41,22 +38,31 @@ jobs:
 
       - name: Run tests on ${{ matrix.os }}
         run: |
-          python -m pip install --upgrade pip
-          pip install -e .[dev]
-          # stop the build if there are Python syntax errors or undefined names
           ruff check . --select=E9,F63,F7,F82
           pytest
 
-      - name: Buid Sphinx doc on ${{ matrix.os }}
-        if: runner.os == 'Linux' && ${{ github.event_name == 'push' && github.ref == 'refs/heads/devel' }} && ${{ matrix.python-version == '3.12'}}
+  Doc:
+    runs-on: ubuntu-latest
+    needs: Test 
+    steps:
+
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+
+      - name: Buid Sphinx doc 
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/devel' }} 
         run: |
-          sudo apt-get update && sudo apt-get -y install make
+          python -m pip install --upgrade pip
           pip install -e .[dev,docs]
           make -C docs html
 
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v4
-        if: runner.os == 'Linux' && ${{ github.event_name == 'push' && github.ref == 'refs/heads/devel' }} && ${{ matrix.python-version == '3.12'}}
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/devel' }} 
         with:
           publish_branch: gh-pages
           github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish.yml

@@ -35,5 +35,5 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           password: ${{ secrets.PYPI_API_TOKEN }}
-          repository-url: https://pypi.org/
+          repository-url: https://upload.pypi.org/legacy/
           verbose: true

docs/Makefile

@@ -14,11 +14,8 @@ $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx in
 endif
 
 # Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) $(SOURCEDIR)
+I18NSPHINXOPTS  = $(PAPEROPT_a4) $(SPHINXOPTS) .
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
 

docs/source/conf.py

@@ -8,6 +8,11 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../../src/momics/"))
+
 from datetime import datetime
 from importlib.metadata import metadata
 
@@ -35,8 +40,9 @@
     "recommonmark",
 ]
 
-numpydoc_show_class_members = False
-napoleon_use_rtype = False
+autosummary_generate = True
+numpydoc_show_class_members = True
+napoleon_use_rtype = True
 autodoc_typehints = "description"
 autodoc_class_signature = "separated"
 templates_path = ["_templates"]
@@ -52,22 +58,8 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "furo"
+# html_theme = "furo"
+html_theme = "pydata_sphinx_theme"
 html_static_path = ["_static"]
 htmlhelp_basename = "momicsdoc"
-
-# -- Options for manual page output ---------------------------------------
-man_pages = [(master_doc, "momics", "momics Documentation", [author], 1)]
-
-# -- Options for Texinfo output -------------------------------------------
-texinfo_documents = [
-    (
-        master_doc,
-        "momics",
-        "momics Documentation",
-        author,
-        "momics",
-        "One line description of project.",
-        "Miscellaneous",
-    ),
-]
+html_last_updated_fmt = "%b %d, %Y"

docs/source/index.rst

@@ -22,9 +22,7 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
-   api
-   Glossary
+   quickstart
+   momics.rst
+   glossary.rst
 
-* :ref:`genindex`
-* :ref:`Glossary`
-

docs/source/modules.rst

@@ -0,0 +1,7 @@
+momics
+======
+
+.. toctree::
+   :maxdepth: 4
+
+   momics

docs/source/momics.rst

@@ -0,0 +1,31 @@
+.. _api:
+
+API
+===
+
+Submodules
+----------
+
+momics.Momics module
+--------------------
+
+.. automodule:: momics.Momics
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+momics.utils module
+-------------------
+
+.. automodule:: momics.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: momics
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/quickstart.rst

@@ -0,0 +1,57 @@
+Quickstart
+==========
+
+Installation
+------------
+
+Install :py:mod:`momics`  from `PyPI <https://pypi.org/project/momics>`_ using :command:`pip`.
+
+::
+
+    $ pip install momics
+
+Requirements:
+
+- Python `3.8` and higher
+- Python packages :py:mod:`tiledb`, :py:mod:`pyarrow`, :py:mod:`numpy`, :py:mod:`scipy`, :py:mod:`pandas`, :py:mod:`pyBigWig`.
+
+We highly recommend using the `conda` package manager to install scientific 
+packages like these. To get :command:`conda`, you can download either the 
+full `Anaconda <https://www.continuum.io/downloads>`_ Python distribution 
+which comes with lots of data science software or the minimal 
+`Miniconda <http://conda.pydata.org/miniconda.html>`_ distribution 
+which is just the standalone package manager plus Python. 
+
+In the latter case, you can install :py:mod:`momics` and all its dependencies as follows:
+
+::
+
+    $ conda install bioconda::momics
+
+
+Command line interface (CLI)
+----------------------------
+
+See:
+
+- The `CLI Reference <http://js2264.github.io/momics/en/latest/cli.html>`_ for more information.
+
+
+The :py:mod:`momics` package includes command line tools for creating, querying and manipulating `.momics` files.
+
+::
+
+    $ momics create --name hg19.momics --chrom hg19.chrom.sizes
+    $ momics ingest hg19.momics a=sample1.bw b=sample2.bw c=sample3.bw
+    $ momics tree hg19.momics
+    $ momics dump --table chroms hg19.momics
+    $ momics dump --table tracks hg19.momics
+    $ momics query --table a --query "I:10-1000" hg19.momics
+    $ momics extract --table a --out a.bw hg19.momics
+
+
+Python API
+----------
+
+See the :ref:`API` for more information.
+

pyproject.toml

@@ -70,12 +70,12 @@ dev = [
 ]
 docs = [
     "autodocsumm",
+    "sphinxcontrib-napoleon", 
     "m2r",
     "recommonmark",
     "Sphinx>=1.6",
     "sphinx-autobuild",
-    "sphinx_rtd_theme",
-    "furo",
+    "pydata-sphinx-theme",
 ]
 
 [tool.ruff]

src/momics/Momics.py

@@ -8,6 +8,14 @@
 
 
 class Momics:
+    """
+    A class to manipulate `.momics` repositories.
+
+    Attributes
+    ----------
+    path : str
+        Path to a `.momics` repository.
+    """
 
     def _get_table(self, tdb: str):
         path = os.path.join(self.path, tdb)
@@ -19,13 +27,14 @@ def _get_table(self, tdb: str):
 
         return a
 
-    def chroms(self, **kwargs):
-        """Extract chromosome lengths table
+    def chroms(self):
+        """
+        A method to extract chromosome table from a `.momics` repository.
 
         Returns
         -------
-        Pandas DataFrame
-
+        pandas.DataFrame
+            A data frame listing one chromosome per row
         """
         tdb = os.path.join("genome", "chroms.tdb")
         chroms = self._get_table(tdb)
@@ -34,13 +43,14 @@ def chroms(self, **kwargs):
 
         return chroms
 
-    def tracks(self, **kwargs):
-        """Extract table of ingested bigwigs
+    def tracks(self):
+        """
+        Extract table of ingested bigwigs
 
         Returns
         -------
-        Pandas
-
+        pandas.DataFrame
+            A data frame listing one ingested bigwig file per row
         """
         tdb = os.path.join("coverage", "tracks.tdb")
         tracks = self._get_table(tdb)
@@ -50,6 +60,14 @@ def tracks(self, **kwargs):
         return tracks
 
     def add_tracks(self, bws: dict):
+        """
+        A method to ingest big wig coverage tracks to the `.momics` repository.
+
+        Parameters
+        ----------
+        bws : dict
+            Dictionary of bigwig files
+        """
 
         # Abort if `chroms` have not been filled
         if self.chroms().empty == True:
@@ -128,7 +146,18 @@ def add_tracks(self, bws: dict):
                         coord2 = np.repeat(idx + n, len(coord1))
                         A[coord1, coord2] = {"scores": arr}
 
-    def add_chroms(self, chr_lengths: dict, genome_version=""):
+    def add_chroms(self, chr_lengths: dict, genome_version: str = ""):
+        """
+        A method to add chromosomes (and genome) information the `.momics` repository.
+
+        Parameters
+        ----------
+        chr_lengths : dict
+            Chromosome lengths
+        genome_version : str
+            Genome version (default: "")
+        """
+
         if self.chroms().empty == False:
             raise ValueError("`chroms` table has already been filled out.")
 
@@ -155,6 +184,14 @@ def add_chroms(self, chr_lengths: dict, genome_version=""):
             array.meta["timestamp"] = datetime.now().isoformat()
 
     def __init__(self, path: str):
+        """
+        Initialize the Momics class.
+
+        Parameters
+        ----------
+        path : str
+            Path to a `.momics` repository.
+        """
 
         self.path = path
         genome_path = os.path.join(path, "genome")