This skill should be used when the user asks to "set up documentation", "create docs for Python package", "configure Sphinx", "set up MkDocs", "write docstrings", "use NumPy-style docstrings", "set up Read the Docs", "integrate Jupyter notebooks in docs", "organize documentation with Diataxis", "create API reference docs", "build documentation with nox", "fix documentation build errors", "documentation build fails", "sphinx warning", "autodoc error", "fix sphinx errors", "make documentation accessible", "accessibility guidelines for docs", "accessible images", "alt text for figures", "colorblind-friendly plots", "color contrast in docs", or needs guidance on scientific Python documentation best practices, Sphinx extensions, documentation themes (pydata-sphinx-theme, furo, material), documentation hosting, accessibility standards, or troubleshooting documentation issues.
View on GitHubplugins/scientific-python-development/skills/scientific-documentation/SKILL.md
January 22, 2026
Select agents to install to:
npx add-skill https://github.com/uw-ssec/rse-plugins/blob/main/plugins/scientific-python-development/skills/scientific-documentation/SKILL.md -a claude-code --skill scientific-documentationInstallation paths:
.claude/skills/scientific-documentation/# Scientific Python Documentation A comprehensive guide to creating documentation for scientific Python packages following community best practices from the [Scientific Python Development Guide](https://learn.scientific-python.org/development/guides/docs/). ## Resources in This Skill This skill includes extensive supporting materials for documentation tasks: **References** (detailed guides): - `references/DIATAXIS_FRAMEWORK.md` - Complete Diátaxis framework guide with examples for all four documentation types - `references/SPHINX_EXTENSIONS.md` - Detailed Sphinx extension configuration and usage - `references/DOCSTRING_EXAMPLES.md` - Comprehensive NumPy-style docstring examples for functions, classes, and modules - `references/NOTEBOOK_INTEGRATION.md` - Jupyter notebook integration guide for Sphinx and MkDocs - `references/COMMON_ISSUES.md` - Troubleshooting documentation build issues - `references/ACCESSIBLE_DOCUMENTATION.md` - Accessibility guidelines for scientific documentation including images, color contrast, and alt text **Assets** (ready-to-use templates): - `assets/sphinx-conf-scientific.py` - Complete Sphinx `conf.py` template for scientific Python - `assets/readthedocs.yaml` - Read the Docs configuration template - `assets/mkdocs-scientific.yml` - MkDocs configuration template with Material theme - `assets/noxfile-docs.py` - Nox automation sessions for documentation builds - `assets/index-template.md` - Documentation landing page template **Scripts**: - `scripts/generate-api-docs.py` - Script to generate API documentation stubs ## Quick Decision Trees ### Documentation Framework Selection Choose your documentation framework based on project needs: **Sphinx** - Best for: - LaTeX/math-heavy documentation - Established scientific Python ecosystem integration - Projects similar to NumPy, SciPy, Astropy - Need for PDF output - Extensive API documentation with autodoc **MkDocs** - Best for: - Markdown-native documentation - Simpler setup with fewer p