Skip to content

Feat/self hosted docs#36

Open
adarshdigievo wants to merge 7 commits into
masterfrom
feat/self-hosted-docs
Open

Feat/self hosted docs#36
adarshdigievo wants to merge 7 commits into
masterfrom
feat/self-hosted-docs

Conversation

@adarshdigievo

Copy link
Copy Markdown
Member

Summary

This PR replaces the old ReadTheDocs/Sphinx documentation setup with a static GitHub Pages site for serpapi-python (using the great-docs Python package).

When docs are built

Deployed docs are built from the release workflow on version tags matching v**.

The release flow is now:

  1. run tests
  2. build distribution
  3. publish release
  4. smoke-test the published PyPI package
  5. build Great Docs
  6. upload and deploy the Pages artifact

New dependency

Adds an optional docs extra:

docs = ["great-docs>=0.12; python_version >= '3.11'"]

New docs tests

Adds doc tests. The code snippets present in docs pages are included in the pytest suite of the package via tests/test_docs_examples.py, which executes Python fenced code blocks from:

  • README.md
  • docs/index.md
  • docs/user_guide/*.md
  • docs/examples/*.md

The test uses SERPAPI_KEY or API_KEY, replaces placeholder secret_api_key values, and supports <!-- docs-test: skip ... --> for examples that should not run, such as proxy/TLS placeholder snippets.

pyproject.toml also enables module doctests for serpapi.

Removed old docs setup

Removes the ReadTheDocs/Sphinx files:

  • .readthedocs.yaml
  • docs/Makefile
  • docs/conf.py
  • docs/requirements.txt
  • docs/index.rst
  • docs/_static/serpapi-python.png

.gitignore now ignores the generated great-docs/ output instead of docs/build.

Docs structure overview

Adds:

  • great-docs.yml for site configuration, navigation, API reference grouping, theme settings, and llms.txt pre-render generation.
  • docs/index.md as the docs homepage.
  • docs/user_guide/ pages for setup, client usage, parameters, pagination, errors/timeouts, account/location helpers, migration, async archive, threading, multiprocessing, zero trace, JSON Restrictor, and request options.
  • docs/examples/ pages grouped by search engines, AI answers, local/maps, shopping, travel, finance/trends/jobs/events, media/apps/research.
  • custom SerpApi branding and docs styling in assets/.
  • scripts/build_llms_txt.py so /llms.txt includes useful homepage/getting-started context, not only API reference links.
  • Python docstrings of core.py and models.py files are changed to match the great-docs supported format.
  • No core code changes are made. PR touches doc-related functionality only.

Screenshots:

image image image

@adarshdigievo adarshdigievo requested review from ilyazub and jvmvik July 10, 2026 18:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant