Skip to content

Commit 5d85430

Browse files
enryHCopilotgithub-actions[bot]Copilot
authored
🎨 add default llms.txt file configuration (#60)
* 🎨 add default llms.txt file configuration - markdown and rst also available. * 📝 link llms text files - have to be configured properly. * 📝 no direct link yet to files * 🔧 configure llms-full txt - files in `_source` folder are considered - notebooks are too verbose? Could be added as .py notebooks (hook into build process) - find a way to build audodoc source files to e.g. markdown to include reference * 🚧 try to run markdown conversion before sphinx run * 🚧 add markdowns manually * 🚧 try to add action that autoupdates Co-authored-by: Copilot <copilot@github.com> * 🐛 add dependency * 🎨 format * 🐛 install dependency for now in action Co-authored-by: Copilot <copilot@github.com> * 🐛 maybe installation issue for plotly? * 🐛 let's try not to run all the notebooks Co-authored-by: Copilot <copilot@github.com> * 📝 update instruction * 🐛 do not treat warnings as errors * 🎨 try to set user.email and user.name - seems to be a generic github runner id * 🎨 update PR Co-authored-by: Copilot <copilot@github.com> * 🎨 update PCA docstring for testing new action Co-authored-by: Copilot <copilot@github.com> * 🐛 correct file path * 🐛 follow instructions of git detached HEAD state * 🐛 fix action to use branch Co-authored-by: Copilot <copilot@github.com> * docs: update markdown reference * docs: update markdown reference * 🎨 only run on upstream, not on forks Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * 📝 update links to llms readable documentation * 🐛 execute notebooks again * Apply suggestions from code review: typos and class ref in docs Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * docs: update markdown reference * 🐛 revert back so the class is linked * docs: update markdown reference * 🐛 use class solution but add intersphinx for sklearn * docs: update markdown reference * 🔥 remove function in conf.py - does not work on readthedocs * add api examples to llms-full.txt * :format: * 🎨 make a new selection of files and document it * 🎨 add markdown only for llms-full.txt * 🎨 format file --------- Co-authored-by: Copilot <copilot@github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
1 parent 240bede commit 5d85430

30 files changed

Lines changed: 3967 additions & 5 deletions

‎.github/workflows/updt_markdowns.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Update Markdown Docs
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
update-markdowns:
13+
if: ${{ github.event.pull_request.head.repo.full_name == github.repository }}
14+
runs-on: ubuntu-latest
15+
16+
steps:
17+
- name: Checkout repo on PR branch
18+
uses: actions/checkout@v4
19+
with:
20+
ref: ${{ github.head_ref }}
21+
fetch-depth: 0
22+
23+
- name: Set up Python
24+
uses: actions/setup-python@v5
25+
with:
26+
python-version: "3.13"
27+
28+
- name: Install docs dependencies
29+
run: |
30+
python -m pip install --upgrade pip
31+
pip install ".[docs]" sphinx-markdown-builder==0.6.9
32+
33+
- name: Build markdown docs
34+
working-directory: docs
35+
run: |
36+
sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../src/acore
37+
rm -r api_examples
38+
rm -r example_data
39+
echo "# Test" > index.md
40+
sphinx-build --keep-going -b markdown ./ ./_build_markdown
41+
rm -r ./markdown_ref
42+
mv ./_build_markdown/reference ./markdown_ref
43+
44+
- name: Commit and push changes
45+
# https://www.junian.net/dev/github-actions-bot-username-email-address/
46+
run: |
47+
git config user.name "github-actions[bot]"
48+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
49+
50+
git add docs/markdown_ref
51+
if git diff --cached --quiet; then
52+
echo "No markdown updates to commit"
53+
exit 0
54+
fi
55+
56+
git commit -m "docs: update markdown reference"
57+
git push origin ${{ github.head_ref }}

‎docs/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
_build
2+
_build_markdown
23
jupyter_execute
34
reference
45
downloaded

‎docs/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,19 @@ Install the docs dependencies of the package (as speciefied in toml):
1515
pip install .[docs]
1616
```
1717

18+
## Updating LLM documentation files
19+
20+
The API reference in `docs/markdown_ref` is updated automatically by the CI workflow.
21+
If you need to regenerate these files locally, or if the automation is unavailable for your branch,
22+
run the following commands manually:
23+
24+
```bash
25+
# we are only interested in the reference files
26+
sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../
27+
sphinx-build -n -W --keep-going -b markdown ./ ./_build_markdown
28+
mv _build_markdown/reference ./markdown_ref
29+
```
30+
1831
## Build docs using Sphinx command line tools
1932

2033
Command to be run from `path/to/docs`, i.e. from within the `docs` package folder:

‎docs/conf.py‎

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@
4141
"sphinx_new_tab_link",
4242
"myst_nb",
4343
"sphinx_copybutton",
44+
"sphinx_llms_txt",
4445
]
4546

4647
myst_enable_extensions = [
@@ -69,6 +70,7 @@
6970
# This patterns also effect to html_static_path and html_extra_path
7071
exclude_patterns = [
7172
"_build",
73+
"_build_markdown",
7274
"Thumbs.db",
7375
".DS_Store",
7476
"jupyter_execute",
@@ -85,7 +87,7 @@
8587
"pandera": ("https://pandera.readthedocs.io/en/stable/", None),
8688
"pydantic": ("https://docs.pydantic.dev/latest", None),
8789
"pingouin": ("https://pingouin-stats.org/", None),
88-
# "scikit-learn": ("https://scikit-learn.org/stable/", None),
90+
"scikit-learn": ("https://scikit-learn.org/stable/", None),
8991
# "matplotlib": ("https://matplotlib.org/stable/", None),
9092
}
9193

@@ -113,6 +115,40 @@
113115
## Generate autodoc stubs with summaries from code
114116
autosummary_generate = True
115117

118+
119+
# llms-txt options
120+
121+
# Content filtering
122+
# in _source folder
123+
llms_txt_exclude = [
124+
"search",
125+
"genindex",
126+
"404",
127+
"index",
128+
"authors",
129+
"history",
130+
"contributing",
131+
"llms", # maybe include it for description of the llms-txt format?
132+
"README",
133+
"home_page",
134+
"reference*",
135+
# exclude ipynb files for now
136+
"example_data*",
137+
"api_examples*",
138+
"downloaded*",
139+
"sections_readme*",
140+
]
141+
142+
143+
# Source code inclusion with include/exclude patterns
144+
llms_txt_code_files = [
145+
# "+:../src/**/*.py", # Include Python files
146+
# "+:../config/*.yaml", # Include config files
147+
"-:../src/**/__pycache__/**", # Exclude cache files
148+
# "-:reference/*.rst", # Exclude markdown files
149+
"+:api_examples/*.py", # Include notebooks in pypercent format
150+
]
151+
116152
# -- General configuration ---------------------------------------------------
117153

118154
myst_enable_extensions = ["dollarmath", "amsmath", "colon_fence"]
@@ -156,7 +192,7 @@
156192
# Add any paths that contain custom static files (such as style sheets) here,
157193
# relative to this directory. They are copied after the builtin static files,
158194
# so a file named "default.css" will overwrite the builtin "default.css".
159-
# html_static_path = ['_static']
195+
# html_static_path = ["_static"]
160196

161197
# -- Setup for sphinx-apidoc -------------------------------------------------
162198

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ reference/acore
6666
:caption: MISC:
6767
:hidden:
6868
69+
llms
6970
contributing
7071
authors
7172
history

‎docs/llms.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# LLM documentation
2+
3+
This website hosts two generated files via
4+
[sphinx-llms-txt](https://sphinx-llms-txt.readthedocs.io/en/latest/getting-started.html):
5+
6+
- `llms-full.txt`: full LLM-oriented documentation of Python API and as source files
7+
all api example notebooks in `docs/api_examples/` (in pypercent format)
8+
- `llms.txt`: short overview of available modules
9+
10+
There is two versions, one of the lastest main branch version of the package
11+
and one of the latest stable release.
12+
13+
## Latest
14+
15+
- [llms-full.txt (latest)](https://analytics-core.readthedocs.io/latest/llms-full.txt)
16+
- [llms.txt (latest)](https://analytics-core.readthedocs.io/latest/llms.txt)
17+
18+
## Stable
19+
20+
- [llms-full.txt (stable)](https://analytics-core.readthedocs.io/stable/llms-full.txt)
21+
- [llms.txt (stable)](https://analytics-core.readthedocs.io/stable/llms.txt)

‎docs/llms_full_describe.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# LLM Full-Txt documentation
2+
3+
This file contains full LLM-oriented documentation of Python API and as source files
4+
all api example notebooks from the `docs/api_examples/` folder (in pypercent format).

‎docs/markdown_ref/acore.batch_correction.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# acore.batch_correction package
2+
3+
### combat_batch_correction(data: DataFrame, batch_col: [str](https://docs.python.org/3/library/stdtypes.html#str)) → DataFrame
4+
5+
This function corrects processed data for batch effects. For more information visit:
6+
[https://github.com/epigenelabs/inmoose](https://github.com/epigenelabs/inmoose)
7+
8+
* **Parameters:**
9+
* **data** – pandas.DataFrame with samples as rows and protein identifiers as columns.
10+
* **batch_col** – column with the batch identifiers
11+
* **Returns:**
12+
pandas.DataFrame with samples as rows and protein identifiers as columns.
13+
14+
Example:
15+
16+
```default
17+
result = combat_batch_correction(
18+
data,
19+
batch_col="batch",
20+
index_cols=["subject", "sample", "group"],
21+
)
22+
```

0 commit comments

Comments
 (0)