Skip to content

Commit 9966b68

Browse files
adarshdigievoadarshdigievo
committed
docs: Enhance ReadTheDocs docs of the package. Add custom theme, user guide, examples and automated publishing on releases
1 parent c124b21 commit 9966b68

96 files changed

Lines changed: 2933 additions & 2790 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -31,12 +31,6 @@ jobs:
3131
run: pip install -e .[test]
3232

3333
- name: Run tests
34-
run: pytest -k "not example"
35-
env:
36-
API_KEY: ${{ secrets.API_KEY }}
37-
38-
- name: Run example tests
39-
if: matrix.python-version == '3.14'
40-
run: pytest -k "example"
34+
run: pytest --ignore=tests/test_docs_publishing.py -k "not example"
4135
env:
4236
API_KEY: ${{ secrets.API_KEY }}

‎.github/workflows/docs.yml‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches: [master]
6+
tags: ['v**']
7+
pull_request:
8+
branches: [master]
9+
workflow_dispatch:
10+
11+
permissions:
12+
contents: read
13+
14+
jobs:
15+
live-examples:
16+
name: Live documentation examples
17+
if: >-
18+
github.actor != 'dependabot[bot]' &&
19+
(github.event_name != 'pull_request' ||
20+
github.event.pull_request.head.repo.full_name == github.repository)
21+
runs-on: ubuntu-latest
22+
timeout-minutes: 30
23+
steps:
24+
- uses: actions/checkout@v6
25+
26+
- uses: actions/setup-python@v6
27+
with:
28+
python-version: "3.13"
29+
30+
- uses: astral-sh/setup-uv@v7
31+
32+
- name: Install test dependencies
33+
run: |
34+
uv venv
35+
uv pip install -e '.[test]'
36+
37+
- name: Run live documentation examples
38+
run: >-
39+
.venv/bin/python -m pytest tests/test_docs_examples.py
40+
--require-docs-key -q --junitxml=docs-example-results.xml
41+
env:
42+
API_KEY: ${{ secrets.API_KEY }}
43+
44+
- uses: actions/upload-artifact@v7
45+
if: always()
46+
with:
47+
name: docs-example-results
48+
path: docs-example-results.xml
49+
if-no-files-found: warn
50+
51+
build:
52+
name: Build Sphinx documentation
53+
needs: [live-examples]
54+
if: >-
55+
always() && !cancelled() &&
56+
(needs.live-examples.result == 'success' || needs.live-examples.result == 'skipped')
57+
runs-on: ubuntu-latest
58+
steps:
59+
- uses: actions/checkout@v6
60+
61+
- uses: actions/setup-python@v6
62+
with:
63+
python-version: "3.13"
64+
65+
- uses: astral-sh/setup-uv@v7
66+
67+
- name: Install documentation dependencies
68+
run: |
69+
uv venv
70+
uv pip install -e '.[docs,test]'
71+
72+
- name: Test documentation publishing
73+
run: .venv/bin/python -m pytest tests/test_docs_publishing.py -q
74+
75+
- name: Check documentation code and test runner without API calls
76+
run: >-
77+
.venv/bin/python -m pytest tests/test_docs_examples.py
78+
tests/test_docs_example_runner.py -k 'not live' -q
79+
80+
- name: Explain unavailable live checks
81+
if: needs.live-examples.result == 'skipped'
82+
run: >-
83+
echo '::notice::Live docs checks need API_KEY and do not run on fork or Dependabot PRs. Run the reviewed revision with a key before merging.'
84+
85+
- name: Build HTML documentation
86+
run: .venv/bin/sphinx-build -M html docs docs/_build -W --keep-going
87+
88+
- name: Build EPUB documentation
89+
run: .venv/bin/sphinx-build -M epub docs docs/_build -W --keep-going
90+
91+
- uses: actions/upload-artifact@v7
92+
with:
93+
name: documentation
94+
path: docs/_build/
95+
if-no-files-found: error
96+
97+
publish:
98+
name: Publish Read the Docs
99+
needs: [live-examples, build]
100+
if: >-
101+
needs.live-examples.result == 'success' &&
102+
needs.build.result == 'success' &&
103+
(github.event_name == 'push' || github.event_name == 'workflow_dispatch') &&
104+
(github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/v'))
105+
runs-on: ubuntu-latest
106+
timeout-minutes: 60
107+
environment:
108+
name: docs
109+
url: https://serpapi-python.readthedocs.io/
110+
concurrency:
111+
group: readthedocs-publish
112+
cancel-in-progress: false
113+
queue: max
114+
steps:
115+
- uses: actions/checkout@v6
116+
with:
117+
ref: ${{ github.sha }}
118+
persist-credentials: false
119+
120+
- uses: actions/setup-python@v6
121+
with:
122+
python-version: "3.13"
123+
124+
- name: Sync versions, publish, and wait for RTD
125+
run: python -m scripts.publish_docs
126+
env:
127+
RTD_API_TOKEN: ${{ secrets.RTD_API_TOKEN }}

‎.github/workflows/release.yml‎

Lines changed: 3 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -38,14 +38,14 @@ jobs:
3838
run: pip install -e .[test]
3939

4040
- name: Run tests
41-
run: pytest -k "not example"
41+
run: pytest --ignore=tests/test_docs_publishing.py -k "not example"
4242
env:
4343
API_KEY: ${{ secrets.API_KEY }}
4444

45-
- name: Run example tests
45+
- name: Run engine and documentation examples
4646
if: matrix.python-version == '3.14'
4747
continue-on-error: ${{ inputs.allow_example_test_failures == true }}
48-
run: pytest -k "example"
48+
run: pytest --ignore=tests/test_docs_publishing.py -k "example" --require-docs-key
4949
env:
5050
API_KEY: ${{ secrets.API_KEY }}
5151

@@ -141,50 +141,3 @@ jobs:
141141
results = client.search({"engine": "google", "q": "coffee"})
142142
assert results.get("organic_results"), "No organic results returned"
143143
print(f"OK: live search returned {len(results['organic_results'])} organic results")
144-
145-
build-docs:
146-
name: Build Great Docs
147-
needs: [smoke-test]
148-
runs-on: ubuntu-latest
149-
steps:
150-
- name: Checkout repository
151-
uses: actions/checkout@v6
152-
with:
153-
fetch-depth: 0
154-
155-
- name: Set up Python
156-
uses: actions/setup-python@v6
157-
with:
158-
python-version: "3.13"
159-
160-
- name: Install package and documentation dependencies
161-
run: |
162-
python -m pip install --upgrade pip
163-
pip install -e ".[docs]"
164-
165-
- name: Set up Quarto
166-
uses: quarto-dev/quarto-actions/setup@v2
167-
168-
- name: Build documentation
169-
run: great-docs build
170-
171-
- name: Upload Pages artifact
172-
uses: actions/upload-pages-artifact@v5
173-
with:
174-
path: great-docs/_site
175-
include-hidden-files: true
176-
177-
deploy-docs:
178-
name: Deploy GitHub Pages
179-
needs: [build-docs]
180-
runs-on: ubuntu-latest
181-
permissions:
182-
pages: write
183-
id-token: write
184-
environment:
185-
name: github-pages
186-
url: ${{ steps.deployment.outputs.page_url }}
187-
steps:
188-
- name: Deploy to GitHub Pages
189-
id: deployment
190-
uses: actions/deploy-pages@v5

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
script/
44
.coverage
5-
great-docs/
5+
docs/_build/
66
dist/
77
build/
88
.pytest_cache/

‎.readthedocs.yaml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
version: 2
2+
3+
build:
4+
os: ubuntu-24.04
5+
tools:
6+
python: "3.13"
7+
jobs:
8+
pre_build:
9+
- python -m scripts.check_docs_revision
10+
- python -m pytest tests/test_docs_examples.py tests/test_docs_example_runner.py -k 'not live' -q
11+
post_build:
12+
- python -m scripts.check_docs_revision
13+
14+
sphinx:
15+
configuration: docs/conf.py
16+
fail_on_warning: true
17+
18+
formats:
19+
- pdf
20+
- epub
21+
22+
python:
23+
install:
24+
- method: uv
25+
command: pip
26+
path: .
27+
extras:
28+
- docs
29+
- test

0 commit comments

Comments
 (0)