From 88532f6d5823e7c8ddccd6ac14ea91e015892d1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ester=20Mu=C3=B1oz=20del=20Campo?= Date: Mon, 17 Jun 2024 15:36:52 +0200 Subject: [PATCH] Start documentation. --- .github/workflows/continuous_integration.yml | 2 +- doc/Makefile | 20 ++++++ doc/_static/custom.css | 4 ++ doc/_templates/custom_method_summary.py | 5 ++ doc/api_reference.rst | 6 ++ doc/conf.py | 68 ++++++++++++++++++++ doc/index.rst | 25 +++++++ doc/installation.rst | 8 +++ doc/make.bat | 35 ++++++++++ doc/prp_engine.rst | 7 ++ doc/prp_id_col.rst | 7 ++ doc/prp_plot.rst | 8 +++ 12 files changed, 194 insertions(+), 1 deletion(-) create mode 100644 doc/Makefile create mode 100644 doc/_static/custom.css create mode 100644 doc/_templates/custom_method_summary.py create mode 100644 doc/api_reference.rst create mode 100644 doc/conf.py create mode 100644 doc/index.rst create mode 100644 doc/installation.rst create mode 100644 doc/make.bat create mode 100644 doc/prp_engine.rst create mode 100644 doc/prp_id_col.rst create mode 100644 doc/prp_plot.rst diff --git a/.github/workflows/continuous_integration.yml b/.github/workflows/continuous_integration.yml index d7b6467..d4c3415 100644 --- a/.github/workflows/continuous_integration.yml +++ b/.github/workflows/continuous_integration.yml @@ -21,7 +21,7 @@ jobs: - name: Install dependencies run: | # I am using the pip installed by conda, bad practice but OK in C/I I think - pip install pyranges-plot==0.0.20 + pip install pyranges-plot==0.0.23 pip install ruff pytest - name: Check formatting with ruff run: | diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..b48f355 --- /dev/null +++ b/doc/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 = . +BUILDDIR = _build + +# Put it first so that make without argument is like make help. +help: + @ -M help + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# make mode option. is meant as a shortcut for . +%: Makefile + @ -M diff --git a/doc/_static/custom.css b/doc/_static/custom.css new file mode 100644 index 0000000..2b8f515 --- /dev/null +++ b/doc/_static/custom.css @@ -0,0 +1,4 @@ +a.monospaced-link { + font-family: monospace; + font-size: x-small; +} diff --git a/doc/_templates/custom_method_summary.py b/doc/_templates/custom_method_summary.py new file mode 100644 index 0000000..500838b --- /dev/null +++ b/doc/_templates/custom_method_summary.py @@ -0,0 +1,5 @@ +{{ fullname | escape | underline }} + +.. currentmodule:: {{ module }} + +.. automethod:: {{ objname }} \ No newline at end of file diff --git a/doc/api_reference.rst b/doc/api_reference.rst new file mode 100644 index 0000000..6a10173 --- /dev/null +++ b/doc/api_reference.rst @@ -0,0 +1,6 @@ +API reference +~~~~~~~~~~~~~ + +#. :doc:`engine <./prp_engine>` +#. :doc:`id_col <./prp_id_col>` +#. :doc:`Plot function <./prp_plot>` diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..8c614f4 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,68 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +from docutils import nodes + + +# -- Project information ----------------------------------------------------- + +project = "pyranges_plot" +copyright = "2024, Ester Muñoz del Campo, Marco Mariotti" +author = "Ester Muñoz del Campo, Marco Mariotti" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. + + +extensions = ["sphinx.ext.autodoc"] +autosummary_generate = True # Enable summary table generation + +autodoc_default_options = { + "members": True, + "imported-members": True, +} + +templates_path = ["_templates"] +html_static_path = ["_static"] + +# exclude_patterns = ['_generated_hidden*'] + +master_doc = "index" + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = "sphinx_rtd_theme" + + +def monospaced_link(name, rawtext, text, lineno, inliner, options={}, content=[]): + url = text.split(" ")[-1].strip("<>") + clickable_text = " ".join(text.split(" ")[:-1]) + # Create a reference node, which is the docutils node for hyperlinks + #unescaped_text = utils.unescape(text) + + node = nodes.reference(rawtext, clickable_text, refuri=url, **options) + + # Add a special class to this node + node["classes"].append("monospaced-link") + return [node], [] + + +def setup(app): + app.add_role("mslink", monospaced_link) + app.add_css_file("custom.css") diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..768d316 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,25 @@ +Pyranges Plot documentation +=========================== + +Pyranges Plot is a Python library specifically tailored to perform +along Pyranges`_ objects. It provides +user-friendly and customizable visualizations for genomic intervals datasets, a perfect +tandem for Pyranges' efficient and intuitive genomic data manipulation methods. + +Plots can be produced in an interactive interface or in batch production, allowing easy +data exploration as well as generation of high quality and reproducible figures. These plots +can be based on either of two engines: Matplotlib and Plotly, to be defined by the user. + +Documentation outline +~~~~~~~~~~~~~~~~~~~~~ +#. :doc:`Installation <./installation>` +#. tutorial +#. api +#. options +(...) +forgot my notebook + +.. toctree:: +(...) + + diff --git a/doc/installation.rst b/doc/installation.rst new file mode 100644 index 0000000..e1fab2f --- /dev/null +++ b/doc/installation.rst @@ -0,0 +1,8 @@ +Installation +~~~~~~~~~~~~ + +Pyranges Plot requires python ≥ 3.12... :: + + pip install pyranges-plot + +sfsbdds \ No newline at end of file diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..374cc7d --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if %SPHINXBUILD% == ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if %1 == goto help + +%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.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/prp_engine.rst b/doc/prp_engine.rst new file mode 100644 index 0000000..d9f24f6 --- /dev/null +++ b/doc/prp_engine.rst @@ -0,0 +1,7 @@ + + + +.. automodule:: pyranges_plot + :members: + :imported-members: # Ensure this is set to include imported members + :exclude-members: plot, set_id_col, get_id_col \ No newline at end of file diff --git a/doc/prp_id_col.rst b/doc/prp_id_col.rst new file mode 100644 index 0000000..d47e79e --- /dev/null +++ b/doc/prp_id_col.rst @@ -0,0 +1,7 @@ + + + +.. automodule:: pyranges_plot + :members: + :imported-members: # Ensure this is set to include imported members + :exclude-members: plot, set_engine, get_engine \ No newline at end of file diff --git a/doc/prp_plot.rst b/doc/prp_plot.rst new file mode 100644 index 0000000..16b8bd4 --- /dev/null +++ b/doc/prp_plot.rst @@ -0,0 +1,8 @@ + + + + +.. automodule:: pyranges_plot + :members: + :imported-members: # Ensure this is set to include imported members + :exclude-members: set_engine, get_engine, set_id_col, get_id_col \ No newline at end of file