Skip to content

Commit 3be7a95

Browse files
kaizhangkaizhang
committed
add docs
1 parent 0881265 commit 3be7a95

File tree

12 files changed

+489
-1
lines changed

12 files changed

+489
-1
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
name: build-documentation
2+
3+
on:
4+
workflow_run:
5+
workflows: [test-python-package]
6+
types:
7+
- completed
8+
9+
jobs:
10+
build_docs:
11+
runs-on: ubuntu-latest
12+
if: ${{ github.event.workflow_run.conclusion == 'success' }}
13+
steps:
14+
- name: Checkout code
15+
uses: nschloe/action-cached-lfs-checkout@v1
16+
with:
17+
ref: ${{ github.event.workflow_run.head_sha }}
18+
19+
- uses: actions/setup-python@v5
20+
name: Install Python
21+
with:
22+
python-version: '3.12'
23+
24+
- name: Install dependency
25+
run: |
26+
sudo apt-get install -y pandoc jq
27+
python -m pip install --upgrade pip --break-system-packages
28+
python -m pip install --user sphinx==8.* pydata-sphinx-theme==0.16.* pandoc nbsphinx \
29+
Pygments==2.19.* sphinx-autodoc-typehints myst-parser \
30+
markupsafe==2.1.* sphinx-plotly-directive
31+
32+
- name: Download wheel files from artifacts
33+
id: download-artifact
34+
uses: dawidd6/action-download-artifact@v2
35+
with:
36+
workflow: test_python.yml
37+
commit: ${{ github.event.workflow_run.head_sha }}
38+
name: wheel-files
39+
path: wheel_files
40+
41+
- name: Install wheel files
42+
run: python -m pip install --user wheel_files/*.whl
43+
44+
- name: Build doc
45+
run: |
46+
python -m sphinx.cmd.build ${GITHUB_WORKSPACE}/docs _build/html
47+
touch _build/html/.nojekyll
48+
49+
- name: Get Package version
50+
id: get_version
51+
run: |
52+
VERSION_NUMBER=$(python -c "import regbench_data;print('.'.join(regbench_data.__version__.split('.')[:2]))")
53+
echo $VERSION_NUMBER
54+
echo "VERSION=$VERSION_NUMBER" >> $GITHUB_ENV
55+
IS_DEV=$(python -c "import regbench_data;print('dev' in regbench_data.__version__)")
56+
echo $IS_DEV
57+
BRANCH_NAME=${{ github.event.workflow_run.head_branch }}
58+
if [[ $IS_DEV == "True" && $BRANCH_NAME == "main" ]]; then
59+
echo "DEPLOY_DEV=true" >> $GITHUB_ENV
60+
elif [[ $BRANCH_NAME =~ ^v[0-9]+ || $BRANCH_NAME == "main" ]]; then
61+
echo "DEPLOY_VERSION=true" >> $GITHUB_ENV
62+
fi
63+
64+
- name: Deploy 🚀
65+
uses: JamesIves/github-pages-deploy-action@v4
66+
if: ${{ env.DEPLOY_DEV == 'true' }}
67+
with:
68+
single-commit: true
69+
branch: gh-pages
70+
folder: _build/html
71+
clean: true
72+
target-folder: /version/dev/
73+
74+
- name: Deploy (version) 🚀
75+
uses: JamesIves/github-pages-deploy-action@v4
76+
if: ${{ env.DEPLOY_VERSION == 'true' }}
77+
with:
78+
single-commit: true
79+
branch: gh-pages
80+
folder: _build/html
81+
clean: true
82+
target-folder: /version/${{ env.VERSION }}/
83+
84+
- name: Fetch JSON and Get Preferred Version
85+
run: |
86+
JSON=$(curl -s "https://raw.githubusercontent.com/regulatory-genomics/regbench_data/main/docs/_static/versions.json")
87+
VERSION=$(echo "$JSON" | jq -r '.[] | select(.preferred == true) | .version')
88+
echo "PREFERRED_VERSION=$VERSION" >> $GITHUB_ENV
89+
echo "Preferred version is $VERSION"
90+
91+
- name: Checkout gh-pages branch
92+
uses: actions/checkout@v4
93+
with:
94+
ref: 'gh-pages'
95+
path: 'gh-pages-folder'
96+
97+
- name: Deploy (preferred version)
98+
uses: JamesIves/github-pages-deploy-action@v4
99+
with:
100+
single-commit: true
101+
branch: gh-pages
102+
folder: gh-pages-folder/version/${{ env.PREFERRED_VERSION }}
103+
clean: true
104+
clean-exclude: version

‎.github/workflows/test_python.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: test-python-package
2+
3+
on: [push, pull_request]
4+
5+
jobs:
6+
build-and-test:
7+
outputs:
8+
VERSION: ${{ steps.get-version.outputs.VERSION }}
9+
runs-on: ubuntu-latest
10+
steps:
11+
- name: Checkout code
12+
uses: nschloe/action-cached-lfs-checkout@v1
13+
14+
- uses: actions/setup-python@v5
15+
name: Install Python
16+
with:
17+
python-version: '3.12'
18+
19+
- name: Install Python dependencies
20+
run: |
21+
python -m pip install --upgrade pip --break-system-packages
22+
python -m pip install --user pytest hypothesis==6.72.4 wheel
23+
24+
- name: Build wheel files
25+
run: |
26+
cd ${GITHUB_WORKSPACE}
27+
mkdir ${GITHUB_WORKSPACE}/wheel_files
28+
pip wheel . --wheel-dir ${GITHUB_WORKSPACE}/wheel_files
29+
30+
- name: Upload wheel files as artifacts
31+
uses: actions/upload-artifact@v4
32+
with:
33+
name: wheel-files
34+
path: ./wheel_files/regbench_data*.whl

‎docs/_static/css/custom.css‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
:root {
2+
// Sidebar styles
3+
--pst-sidebar-secondary: 15rem;
4+
}
5+
6+
/* Main page overview cards */
7+
8+
.bd-page-width {
9+
max-width: 98rem;
10+
}
11+
12+
/* Dark theme tweaking */
13+
html[data-theme=dark] .sd-card img[src*='.svg'] {
14+
filter: invert(0.82) brightness(0.8) contrast(1.2);
15+
}

‎docs/_static/versions.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
[
2+
{
3+
"name": "dev",
4+
"version": "dev",
5+
"url": "https://lab.kaizhang.org/regbench_data/version/dev/"
6+
},
7+
{
8+
"name": "0.1 (stable)",
9+
"version": "0.1",
10+
"preferred": true,
11+
"url": "https://lab.kaizhang.org/regbench_data/version/0.1/"
12+
}
13+
]

‎docs/_templates/autosummary/class.rst‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. currentmodule:: {{ module }}
4+
5+
.. autoclass:: {{ objname }}
6+
7+
{% block attributes %}
8+
{% if attributes %}
9+
.. rubric:: Attributes
10+
11+
.. autosummary::
12+
:toctree: .
13+
{% for item in attributes %}
14+
~{{ objname }}.{{ item }}
15+
{%- endfor %}
16+
{% endif %}
17+
{% endblock %}
18+
19+
{% block methods %}
20+
{% if methods %}
21+
.. rubric:: Methods
22+
23+
.. autosummary::
24+
:toctree: .
25+
{% for item in methods %}
26+
{%- if item != '__init__' %}
27+
~{{ objname }}.{{ item }}
28+
{%- endif -%}
29+
{%- endfor %}
30+
{% endif %}
31+
{% endblock %}

‎docs/_templates/layout.html‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{% extends "!layout.html" %}
2+
3+
{%- block extrahead %}
4+
{{ super() }}
5+
<!-- Google tag (gtag.js) -->
6+
<script async src="https://www.googletagmanager.com/gtag/js?id=G-ZX9JB19KRP"></script>
7+
<script>
8+
window.dataLayer = window.dataLayer || [];
9+
function gtag(){dataLayer.push(arguments);}
10+
gtag('js', new Date());
11+
12+
gtag('config', 'G-ZX9JB19KRP');
13+
</script>
14+
{% endblock %}

‎docs/api.rst‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
=============
2+
API reference
3+
=============
4+
5+
This page gives an overview of all public precellar objects, functions and
6+
methods.
7+
8+
.. currentmodule:: regbench_data
9+
10+
Assay data
11+
~~~~~~~~~~
12+
13+
.. autosummary::
14+
:toctree: _autosummary
15+
16+
assay.fetch_cage
17+
18+
Enhancer data
19+
~~~~~~~~~~~~~
20+
21+
.. autosummary::
22+
:toctree: _autosummary
23+
24+
enhancer.Dataset
25+
enhancer.ScreeningResult
26+
enhancer.concatenate
27+
enhancer.retrieve_datasets
28+
enhancer.Gasperini2019
29+
enhancer.Nasser2021
30+
enhancer.Schraivogel2020
31+
32+
Genome data
33+
~~~~~~~~~~~
34+
35+
.. autosummary::
36+
:toctree: _autosummary
37+
38+
genome.fetch_genome_fasta
39+
genome.fetch_genome_annotation

‎docs/conf.py‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# -- Path setup --------------------------------------------------------------
2+
3+
import re
4+
5+
import regbench_data as my_module
6+
module_name = "regbench_data"
7+
8+
# -- Software version --------------------------------------------------------
9+
10+
# The short X.Y version (including .devXXXX, -devXXXX, rcX, b1 suffixes if present)
11+
version = re.sub(r'(\d+\.\d+)\.\d+([-\.].*)?', r'\1\2', my_module.__version__)
12+
version = re.sub(r'([-\.]dev\d+).*?$', r'\1', version)
13+
14+
# The full version, including alpha/beta/rc tags.
15+
release = my_module.__version__
16+
17+
# pyData/Sphinx-Theme version switcher
18+
if "dev" in version:
19+
switcher_version = "dev"
20+
else:
21+
switcher_version = f"{version}"
22+
23+
print(f'Building documentation for {module_name} {release} (short version: {version}, switcher version: {switcher_version})')
24+
25+
# -- Project information -----------------------------------------------------
26+
27+
project = 'genomics-dataloader'
28+
copyright = '2025, Regulatory Genomics Lab, Westlake University'
29+
author = 'Kai Zhang'
30+
31+
# -- General configuration ---------------------------------------------------
32+
33+
suppress_warnings = ['ref.citation']
34+
default_role = 'code'
35+
add_function_parentheses = False
36+
37+
# Add any Sphinx extension module names here, as strings. They can be
38+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
39+
# ones.
40+
extensions = [
41+
"nbsphinx",
42+
"myst_parser",
43+
"sphinx.ext.autodoc",
44+
"sphinx.ext.intersphinx",
45+
"sphinx.ext.autosummary",
46+
"sphinx.ext.coverage",
47+
"sphinx.ext.mathjax",
48+
"sphinx.ext.napoleon",
49+
"sphinx_autodoc_typehints",
50+
"sphinx_plotly_directive",
51+
]
52+
53+
source_suffix = {
54+
'.rst': 'restructuredtext',
55+
'.txt': 'markdown',
56+
'.md': 'markdown',
57+
}
58+
59+
myst_enable_extensions = [
60+
"amsmath",
61+
#"colon_fence",
62+
#"deflist",
63+
"dollarmath",
64+
#"fieldlist",
65+
#"html_admonition",
66+
#"html_image",
67+
#"linkify",
68+
#"replacements",
69+
#"smartquotes",
70+
#"strikethrough",
71+
#"substitution",
72+
#"tasklist",
73+
]
74+
75+
# Generate the API documentation when building
76+
autosummary_generate = True
77+
autodoc_member_order = 'bysource'
78+
# autodoc_default_flags = ['members']
79+
napoleon_google_docstring = False
80+
napoleon_numpy_docstring = True
81+
napoleon_include_init_with_doc = False
82+
napoleon_use_rtype = True # having a separate entry generally helps readability
83+
napoleon_use_param = True
84+
napoleon_custom_sections = [('Params', 'Parameters')]
85+
todo_include_todos = False
86+
87+
intersphinx_mapping = {
88+
"numpy": ("https://numpy.org/doc/stable/", None),
89+
"python": ("https://docs.python.org/3", None),
90+
}
91+
92+
smv_branch_whitelist = r'main' # Include all branches
93+
94+
# Add any paths that contain templates here, relative to this directory.
95+
templates_path = ['_templates']
96+
97+
# List of patterns, relative to source directory, that match files and
98+
# directories to ignore when looking for source files.
99+
# This pattern also affects html_static_path and html_extra_path.
100+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
101+
102+
103+
# -- Options for HTML output -------------------------------------------------
104+
105+
html_theme = 'pydata_sphinx_theme'
106+
html_show_sphinx = False
107+
html_show_sourcelink = False
108+
html_static_path = ['_static']
109+
html_css_files = [
110+
'css/custom.css',
111+
]
112+
113+
html_theme_options = {
114+
"logo": {
115+
"text": module_name,
116+
"image_dark": "_static/logo-dark.svg",
117+
"alt_text": module_name,
118+
},
119+
120+
"github_url": f"https://github.com/regulatory-genomics/{module_name}",
121+
"external_links": [
122+
],
123+
"header_links_before_dropdown": 6,
124+
125+
"navbar_center": ["version-switcher", "navbar-nav"],
126+
"navbar_end": ["theme-switcher", "navbar-icon-links"],
127+
"navbar_align": "left",
128+
"show_version_warning_banner": switcher_version == "dev",
129+
130+
"switcher": {
131+
"version_match": switcher_version,
132+
"json_url": f"https://raw.githubusercontent.com/regulatory-genomics/{module_name}/refs/heads/main/docs/_static/versions.json",
133+
},
134+
}

0 commit comments

Comments
 (0)