Skip to content

Commit 54fa944

Browse files
MikeLippincottMikeLippincott
authored
Rtd (#110)
* Read the docs * rtd CI * rtd CI * rtd CI * rtd CI * rm build files * clean up script * addressing comments
1 parent 53ebf4e commit 54fa944

27 files changed

+1827
-0
lines changed

‎.github/workflows/auto_upadate.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: Update Docs on Release
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
inputs:
8+
version:
9+
description: 'Version to tag'
10+
required: true
11+
12+
jobs:
13+
update-docs:
14+
runs-on: ubuntu-latest
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Set up Python
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: '3.11'
23+
24+
- name: Update version in docs
25+
run: |
26+
VERSION="${{ github.event.release.tag_name || github.event.inputs.version }}"
27+
sed -i "s/release = '.*'/release = '$VERSION'/" docs/source/conf.py
28+
29+
- name: Commit and push
30+
run: |
31+
git config --local user.email "github-actions[bot]@users.noreply.github.com"
32+
git config --local user.name "github-actions[bot]"
33+
git add docs/source/conf.py
34+
git commit -m "Update docs version to $VERSION" || echo "No changes"
35+
git push
36+
37+
- name: Trigger RTD build
38+
run: |
39+
curl -X POST \
40+
-H "Authorization: Token ${{ secrets.RTD_WEBHOOK_TOKEN }}" \
41+
https://readthedocs.org/api/v3/projects/nf1-3d-organoid-profiling-pipeline/versions/latest/builds/

‎.github/workflows/docs.yml‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
name: Build and Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- develop
8+
paths:
9+
- 'docs/**'
10+
- '.readthedocs.yaml'
11+
- '.github/workflows/docs.yml'
12+
pull_request:
13+
branches:
14+
- main
15+
paths:
16+
- 'docs/**'
17+
workflow_dispatch: # Allow manual trigger
18+
19+
jobs:
20+
build-docs:
21+
runs-on: ubuntu-latest
22+
23+
steps:
24+
- name: Checkout repository
25+
uses: actions/checkout@v4
26+
with:
27+
fetch-depth: 0 # Fetch all history for proper version detection
28+
29+
- name: Set up Python
30+
uses: actions/setup-python@v5
31+
with:
32+
python-version: '3.11'
33+
cache: 'pip'
34+
35+
- name: Install dependencies
36+
run: |
37+
python -m pip install --upgrade pip
38+
pip install -r docs/requirements.txt
39+
40+
- name: Build documentation
41+
run: |
42+
cd docs
43+
make clean
44+
make html
45+
46+
- name: Check for broken links
47+
run: |
48+
cd docs
49+
make linkcheck
50+
continue-on-error: true
51+
52+
- name: Upload documentation artifacts
53+
uses: actions/upload-artifact@v4
54+
with:
55+
name: documentation-html
56+
path: docs/_build/html/
57+
retention-days: 7
58+
59+
- name: Check documentation coverage
60+
run: |
61+
cd docs
62+
make coverage
63+
continue-on-error: true
64+
65+
deploy-rtd:
66+
needs: build-docs
67+
runs-on: ubuntu-latest
68+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
69+
70+
steps:
71+
- name: Trigger Read the Docs build
72+
run: |
73+
curl -X POST \
74+
-H "Authorization: Token ${{ secrets.RTD_WEBHOOK_TOKEN }}" \
75+
https://readthedocs.org/api/v3/projects/nf1-3d-organoid-profiling-pipeline/versions/latest/builds/

‎.github/workflows/testing.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Test Documentation
2+
3+
on:
4+
pull_request:
5+
branches: [main, develop]
6+
paths:
7+
- 'docs/**'
8+
- '**.rst'
9+
- '**.md'
10+
11+
jobs:
12+
test-docs:
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- uses: actions/checkout@v4
17+
18+
- name: Set up Python
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version: '3.11'
22+
23+
- name: Install dependencies
24+
run: |
25+
pip install -r docs/requirements.txt
26+
pip install doc8 sphinx-lint
27+
28+
- name: Check RST syntax
29+
run: |
30+
doc8 docs/source --max-line-length 100
31+
32+
- name: Lint Sphinx files
33+
run: |
34+
sphinx-lint docs/source
35+
36+
- name: Build docs (strict mode)
37+
run: |
38+
cd docs
39+
sphinx-build -W -b html source _build/html
40+
41+
- name: Check links
42+
run: |
43+
cd docs
44+
make linkcheck

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,3 +198,5 @@ profile_prep_for_sage/data_for_sage/*
198198
7.technical_analysis/processed_data/*
199199
7.technical_analysis/results/*
200200
models/*
201+
docs/doctrees/*
202+
docs/html/*

‎.readthedocs.yaml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Read the Docs configuration file
2+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
3+
4+
version: 2
5+
6+
build:
7+
os: ubuntu-22.04
8+
tools:
9+
python: "3.11"
10+
11+
# Build documentation in the docs/ directory with Sphinx
12+
sphinx:
13+
configuration: docs/source/conf.py
14+
fail_on_warning: false
15+
16+
# Python dependencies
17+
python:
18+
install:
19+
- requirements: docs/requirements.txt

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@ To address this, we have developed a 3D patient-derived tumor organoid model of
77
We developed a modified 3D Cell Painting protocol to generate high-content imaging data from these organoids.
88
This repository contains the code and documentation for a comprehensive analysis pipeline to process and analyze these 3D organoid models of NF1 NFs.
99

10+
11+
### Documenation
12+
[![Documentation Status](https://readthedocs.org/projects/nf1-3d-organoid-profiling-pipeline/badge/?version=latest)](https://nf1-3d-organoid-profiling-pipeline.readthedocs.io/en/latest/?badge=latest)
13+
1014
---
1115
### Raw channels
1216
| 405 | 488 | 555 | 640 |

‎docs/Makefile‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Makefile for Sphinx documentation
2+
3+
# You can set these variables from the command line.
4+
SPHINXOPTS = -W --keep-going
5+
SPHINXBUILD = sphinx-build
6+
PAPER =
7+
BUILDDIR = build
8+
SOURCEDIR = source
9+
10+
# Internal variables
11+
PAPEROPT_a4 = -D latex_paper_size=a4
12+
PAPEROPT_letter = -D latex_paper_size=letter
13+
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
14+
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
15+
16+
help:
17+
@echo "Please use \`make <target>' where <target> is one of"
18+
@echo " html to make standalone HTML files"
19+
@echo " dirhtml to make HTML files named index.html in directories"
20+
@echo " singlehtml to make a single large HTML file"
21+
@echo " pickle to make pickle files"
22+
@echo " json to make JSON files"
23+
@echo " htmlhelp to make HTML files and a HTML help project"
24+
@echo " qthelp to make HTML files and a qthelp project"
25+
@echo " devhelp to make HTML files and a Devhelp project"
26+
@echo " epub to make an EPUB file"
27+
@echo " latex to make LaTeX files"
28+
@echo " latexpdf to make LaTeX files and run them through pdflatex"
29+
@echo " latexpdfja to make LaTeX files and run them through Japanese pdflatex"
30+
@echo " text to make text files"
31+
@echo " man to make manual pages"
32+
@echo " texinfo to make Texinfo files"
33+
@echo " gettext to make PO message catalogs"
34+
@echo " changes to make an overview of all changed/added/deprecated items"
35+
@echo " xml to make Docutils-native XML files"
36+
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
37+
@echo " linkcheck to check all external links for integrity"
38+
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
39+
@echo " coverage to run coverage check of the documentation (if enabled)"
40+
41+
clean:
42+
-rm -rf $(BUILDDIR)/*
43+
44+
html:
45+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
46+
@echo
47+
@echo "Build finished. The HTML files are in $(BUILDDIR)/html."
48+
49+
dirhtml:
50+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
51+
@echo
52+
@echo "Build finished. The HTML files are in $(BUILDDIR)/dirhtml."
53+
54+
singlehtml:
55+
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
56+
@echo
57+
@echo "Build finished. The singlehtml files are in $(BUILDDIR)/singlehtml."
58+
59+
pickle:
60+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
61+
@echo
62+
@echo "Build finished. The pickle files are in $(BUILDDIR)/pickle."
63+
64+
json:
65+
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
66+
@echo
67+
@echo "Build finished. The JSON files are in $(BUILDDIR)/json."
68+
69+
htmlhelp:
70+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
71+
@echo
72+
@echo "Build finished. The htmlhelp files are in $(BUILDDIR)/htmlhelp."
73+
74+
qthelp:
75+
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
76+
@echo
77+
@echo "Build finished. The qthelp files are in $(BUILDDIR)/qthelp."
78+
79+
devhelp:
80+
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
81+
@echo
82+
@echo "Build finished. The devhelp files are in $(BUILDDIR)/devhelp."
83+
84+
epub:
85+
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
86+
@echo
87+
@echo "Build finished. The epub files are in $(BUILDDIR)/epub."
88+
89+
latex:
90+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
91+
@echo
92+
@echo "Build finished. The latex files are in $(BUILDDIR)/latex."
93+
94+
latexpdf:
95+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
96+
@echo "Running LaTeX files through pdflatex..."
97+
$(MAKE) -C $(BUILDDIR)/latex all-pdf
98+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
99+
100+
latexpdfja:
101+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
102+
@echo "Running LaTeX files through Japanese pdflatex..."
103+
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
104+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
105+
106+
text:
107+
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
108+
@echo
109+
@echo "Build finished. The text files are in $(BUILDDIR)/text."
110+
111+
man:
112+
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
113+
@echo
114+
@echo "Build finished. The man files are in $(BUILDDIR)/man."
115+
116+
texinfo:
117+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
118+
@echo
119+
@echo "Build finished. The texinfo files are in $(BUILDDIR)/texinfo."
120+
121+
gettext:
122+
$(SPHINXBUILD) -b gettext $(ALLSPHINXOPTS) $(BUILDDIR)/locale
123+
@echo
124+
@echo "Build finished. The gettext files are in $(BUILDDIR)/locale."
125+
126+
changes:
127+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
128+
@echo
129+
@echo "The overview file is in $(BUILDDIR)/changes."
130+
131+
linkcheck:
132+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
133+
@echo
134+
@echo "Link check complete; look for any errors in the above output or in $(BUILDDIR)/linkcheck/index.html."
135+
136+
doctest:
137+
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
138+
@echo
139+
@echo "Doctest complete; look for any errors in the above output or in $(BUILDDIR)/doctest/index.html."
140+
141+
coverage:
142+
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
143+
@echo
144+
@echo "Coverage complete; look for any errors in the above output or in $(BUILDDIR)/coverage/html/index.html."
145+
146+
xml:
147+
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
148+
@echo
149+
@echo "Build finished. The xml files are in $(BUILDDIR)/xml."
150+
151+
pseudoxml:
152+
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
153+
@echo
154+
@echo "Build finished. The pseudoxml files are in $(BUILDDIR)/pseudoxml."

‎docs/call_make_file_in_environment.sh‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
#!/bin/bash
2+
3+
view=True
4+
5+
conda activate NF1_3D_featurization_sphinx_env
6+
7+
make clean
8+
make html
9+
10+
conda deactivate
11+
12+
if [ "$view" = True ] ; then
13+
firefox build/html/index.html
14+
fi

‎docs/requirements.txt‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Sphinx and extensions
2+
sphinx>=7.0
3+
sphinx-rtd-theme>=2.0
4+
sphinx-autodoc-typehints>=1.25
5+
myst-parser>=2.0
6+
sphinxcontrib-napoleon>=0.7
7+
8+
# Minimal dependencies
9+
numpy>=1.24
10+
pandas>=2.0

0 commit comments

Comments
 (0)