Skip to content

docs: Sphinx setup for Read the Docs hosting#44

Merged
ColonistOne merged 1 commit intomainfrom
docs/readthedocs
Apr 27, 2026
Merged

docs: Sphinx setup for Read the Docs hosting#44
ColonistOne merged 1 commit intomainfrom
docs/readthedocs

Conversation

@ColonistOne
Copy link
Copy Markdown
Collaborator

Summary

  • New `docs/` with Sphinx + Furo theme + autodoc + intersphinx + MyST.
  • New `.readthedocs.yaml` (v2 config) so docs auto-build at https://colony-sdk.readthedocs.io on every push to `main` once the project is imported on RTD.
  • `pyproject.toml` gains `Documentation` and `Changelog` entries under `[project.urls]` so PyPI's sidebar surfaces them.

Pages

Page What's there
`docs/index.rst` Landing — sync vs async clients, install snippet, useful-links section
`docs/quickstart.rst` Auth, reading a feed, posting/commenting/reacting, DMs, async, error-handling, webhooks
`docs/api/client.rst` `automodule:: colony_sdk.client` — full sync API
`docs/api/async_client.rst` `automodule:: colony_sdk.async_client`
`docs/api/models.rst` `automodule:: colony_sdk.models`
`docs/api/exceptions.rst` The four error classes, with `:no-index:` to avoid duplicate-object warnings since automodule on `client` already documents them

Local build

```bash
uv venv .venv-docs --python 3.12
uv pip install --python .venv-docs/bin/python sphinx furo myst-parser sphinx-autodoc-typehints
uv pip install --python .venv-docs/bin/python -e ".[async]"
.venv-docs/bin/sphinx-build -b html docs docs/_build/html
```

Build succeeds locally with 4 cosmetic warnings (RetryConfig dataclass field duplicates — autodoc nuance, not blocking; `fail_on_warning: false` in `.readthedocs.yaml` accordingly).

Test plan

  • Local Sphinx build succeeds (`docs/_build/html/index.html` renders correctly under Furo).
  • Once merged: import `colony-sdk-python` on readthedocs.org as ColonistOne (separate manual step), verify first build is green.
  • Verify the `Documentation` link on https://pypi.org/project/colony-sdk/ resolves to https://colony-sdk.readthedocs.io after the next package release.

Adds a docs/ folder with Sphinx + Furo theme + autodoc + intersphinx,
plus a .readthedocs.yaml v2 config so the docs auto-build at
colony-sdk.readthedocs.io on every push to main.

Pages:
- index.rst — landing
- quickstart.rst — auth, feed, posting, async, error-handling, webhooks
- api/client.rst, async_client.rst, models.rst, exceptions.rst — autodoc

Adds Documentation + Changelog entries to [project.urls] in pyproject.toml.
@codecov
Copy link
Copy Markdown

codecov Bot commented Apr 27, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@ColonistOne ColonistOne merged commit 17e4cd9 into main Apr 27, 2026
7 checks passed
@ColonistOne ColonistOne deleted the docs/readthedocs branch April 27, 2026 20:44
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