Skip to content

Modernize RTD documentation with Furo theme and improved structure - #15

Merged
johnbrandborg merged 1 commit into
mainfrom
docs/improve-documentation-and-presentation
Feb 20, 2026
Merged

Modernize RTD documentation with Furo theme and improved structure#15
johnbrandborg merged 1 commit into
mainfrom
docs/improve-documentation-and-presentation

Conversation

@johnbrandborg

Copy link
Copy Markdown
Owner

Summary

  • Furo theme: Replaces Alabaster with a modern, dark-mode-capable, responsive theme used by pip, black, urllib3, etc.
  • New Sphinx extensions: Added sphinx-copybutton (copy buttons on code blocks), sphinx-design (tabbed comparison layouts), intersphinx (cross-links to Python/urllib3 docs), and sphinxext-opengraph (social sharing meta tags).
  • Structural improvements: Fixed user_guide.rst title mismatch, replaced redundant modules.rst/cruds.rst with a single api.rst, added CI/RTD/PyPI badges to index, expanded development.rst with testing and contribution guidance, and refactored the library comparison section into tabbed layouts.
  • Bug fixes: Copyright year is now dynamic, project URLs use https for RTD links, .readthedocs.yaml properly installs the package with [rtd] extras, and shell commands use code-block:: console for proper highlighting.

Test plan

  • Sphinx build completes with zero warnings locally
  • Verify RTD build succeeds after merge
  • Spot-check rendered pages: index, user guide (tabs), API reference, development
  • Confirm dark mode toggle works in Furo
  • Confirm copy buttons appear on code blocks

Made with Cursor

…sions

- Switch from Alabaster to Furo theme for modern look, dark mode, and
  responsive layout
- Add sphinx-copybutton, sphinx-design, intersphinx, and opengraph extensions
- Refactor comparison section to use tabbed layouts instead of long
  sequential code blocks
- Fix user_guide.rst title mismatch (was "Installation", now "User Guide")
- Replace redundant modules.rst/cruds.rst chain with single api.rst
- Add CI, RTD, and PyPI version badges to index page
- Use code-block:: console for shell commands (proper highlighting)
- Expand development.rst with testing, code quality, and issue filing sections
- Fix copyright year to be dynamic (2020-current)
- Fix project.urls to use https for RTD links
- Configure .readthedocs.yaml to install package with [rtd] extras

Co-authored-by: Cursor <cursoragent@cursor.com>
@johnbrandborg
johnbrandborg force-pushed the docs/improve-documentation-and-presentation branch from a7e9ad0 to c777429 Compare February 20, 2026 12:53
@sonarqubecloud

Copy link
Copy Markdown

@johnbrandborg
johnbrandborg merged commit 334724f into main Feb 20, 2026
6 checks passed
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