From python3-development
Generates PyPI-compliant README files in Markdown or reStructuredText for Python packages. Fixes rendering issues, converts formats, validates with twine, and configures pyproject.toml.
npx claudepluginhub jamie-bitflight/claude_skills --plugin python3-developmentThis skill uses the workspace's default tool permissions.
Generate professional, PyPI-compliant README files in Markdown or reStructuredText that render correctly on PyPI, GitHub, GitLab, and BitBucket.
Generates PyPI-compliant README files in Markdown or reStructuredText for Python packages. Useful for publication prep, twine check fixes, format conversion between MD/RST, and pyproject.toml readme configuration.
Generates or audits README.md files compliant with the Standard Readme specification, enforcing exact section order from Title to License. Use write mode to create/rewrite or audit mode to review.
Generates customized README.md templates by analyzing repo structure, package.json, pyproject.toml, and Cargo.toml. Use for new projects, doc improvements, open source prep, or onboarding.
Share bugs, ideas, or general feedback.
Generate professional, PyPI-compliant README files in Markdown or reStructuredText that render correctly on PyPI, GitHub, GitLab, and BitBucket.
Use this skill when:
pyproject.toml metadata for README inclusionPyPI's README renderer supports three formats with specific constraints:
Plain Text (text/plain)
reStructuredText (text/x-rst)
:py:func:, :ref:, :doc:, or other Sphinx-specific rolessphinx-readme extension to generate PyPI-compatible RST from Sphinx docsMarkdown (text/markdown)
Choose Markdown when:
Choose reStructuredText when:
sphinx-readme to generate from Sphinx docsUse sphinx-readme when:
Include these sections for comprehensive project documentation:
Project Identity (Required)
Installation (Required)
pip install package-nameuv add package-name, development installationQuick Start (Highly Recommended)
Features (Recommended)
Usage Examples (Recommended)
Documentation Link (Required if comprehensive docs exist)
Contributing (Recommended for open source)
License (Required)
Changelog/Release Notes (Optional)
Follow these principles from documentation-expert and gitlab-docs-expert:
Clarity and Simplicity
Focus on the User
Accuracy and Synchronization
Promote Consistency
Leverage Visuals and Examples
Syntax Highlighting
```python
import package_name
result = package_name.process("example")
print(result)
# Output: Processed: example
```
Badges
Tables
| Feature | Support |
|---------|---------|
| Python 3.11+ | ✓ |
| Type hints | ✓ |
| Async support | ✓ |
Alerts (GitHub/GitLab)
> [!NOTE]
> This feature requires Python 3.11 or higher.
> [!WARNING]
> Breaking changes in version 2.0. See migration guide.
Links
[Documentation](https://package-name.readthedocs.io)
[PyPI](https://pypi.org/project/package-name/)
[Issues](https://github.com/user/package-name/issues)
Syntax Highlighting
.. code-block:: python
import package_name
result = package_name.process("example")
print(result)
# Output: Processed: example
Badges
.. image:: https://img.shields.io/pypi/v/package-name.svg
:target: https://pypi.org/project/package-name/
:alt: PyPI version
.. image:: https://img.shields.io/pypi/pyversions/package-name.svg
:alt: Python versions
Tables
+------------------+----------+
| Feature | Support |
+==================+==========+
| Python 3.11+ | ✓ |
+------------------+----------+
| Type hints | ✓ |
+------------------+----------+
Or using simple table syntax:
======== =========
Feature Support
======== =========
Python 3.11+ ✓
Type hints ✓
======== =========
Admonitions
.. note::
This feature requires Python 3.11 or higher.
.. warning::
Breaking changes in version 2.0. See migration guide.
.. tip::
Use the async API for better performance.
Links
`Documentation <https://package-name.readthedocs.io>`_
`PyPI <https://pypi.org/project/package-name/>`_
`Issues <https://github.com/user/package-name/issues>`_
Section Headers
================
Main Title
================
Section
=========
Subsection
-----------
Subsubsection
^^^^^^^^^^^^^^
For projects using Sphinx, leverage sphinx-readme to generate PyPI-compatible README.rst files.
Installation
uv add --group docs sphinx-readme
Configuration in conf.py
extensions = [
'sphinx_readme',
]
# Optional configuration
readme_config = {
'src_file': 'index.rst', # Source file in docs/
'out_file': '../README.rst', # Output to project root
}
Key Benefits
Limitations
:py:func:, :ref:) converted to plain text or removedWorkflow
# Build Sphinx docs (generates README.rst automatically)
uv run sphinx-build -b html docs/ docs/_build/html
# Verify README rendering
uv run --with twine twine check dist/*
For Markdown README
[project]
name = "package-name"
version = "1.0.0"
description = "Short one-line description"
readme = "README.md" # Automatically sets content-type to text/markdown
requires-python = ">=3.11"
license = {text = "MIT"}
authors = [
{name = "Your Name", email = "you@example.com"}
]
keywords = ["keyword1", "keyword2"]
classifiers = [
"Development Status :: 4 - Beta",
"Intended Audience :: Developers",
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
]
[project.urls]
Homepage = "https://github.com/user/package-name"
Documentation = "https://package-name.readthedocs.io"
Repository = "https://github.com/user/package-name"
Issues = "https://github.com/user/package-name/issues"
Changelog = "https://github.com/user/package-name/blob/main/CHANGELOG.md"
For reStructuredText README
[project]
readme = "README.rst" # Automatically sets content-type to text/x-rst
# ... rest of configuration
For custom content type
[project]
readme = {file = "README.md", content-type = "text/markdown"}
# or
readme = {file = "README.rst", content-type = "text/x-rst"}
For GitHub Flavored Markdown (explicit)
[project]
readme = {file = "README.md", content-type = "text/markdown; variant=GFM"}
For CommonMark
[project]
readme = {file = "README.md", content-type = "text/markdown; variant=CommonMark"}
Build distribution packages
# Using uv (modern approach)
uv build
# Outputs to dist/:
# - package_name-1.0.0-py3-none-any.whl
# - package_name-1.0.0.tar.gz
Validate README rendering
# Check that README will render on PyPI
uv run --with twine twine check dist/*
Expected output for success:
Checking dist/package_name-1.0.0-py3-none-any.whl: Passed
Checking dist/package_name-1.0.0.tar.gz: Passed
Common validation errors
| Error | Cause | Solution |
|---|---|---|
Unknown interpreted text role "py:func" | Sphinx role in RST | Remove Sphinx-specific roles, use plain text |
Unexpected indentation | RST indentation error | Fix indentation, ensure blank lines before/after directives |
Unknown directive type "automodule" | Sphinx directive in RST | Remove Sphinx directives, use standard docutils only |
Invalid markup | Malformed RST | Run rst2html.py README.rst /dev/null to test |
| Content not showing | Wrong content-type | Verify readme setting in pyproject.toml matches file format |
Publish to PyPI
# Upload to PyPI (requires API token)
uv run --with twine twine upload dist/*
# Test on TestPyPI first (recommended)
uv run --with twine twine upload --repository testpypi dist/*
Setting up PyPI credentials
# Create ~/.pypirc
cat > ~/.pypirc << 'EOF'
[pypi]
username = __token__
password = pypi-your-api-token-here
[testpypi]
username = __token__
password = pypi-your-testpypi-token-here
EOF
chmod 600 ~/.pypirc
Run this workflow before publishing to PyPI:
# 1. Build the package
uv build
# 2. Validate README rendering
uv run --with twine twine check dist/*
# 3. Test installation locally
uv pip install dist/*.whl
# 4. Upload to TestPyPI
uv run --with twine twine upload --repository testpypi dist/*
# 5. Visit TestPyPI page and verify README renders correctly
# https://test.pypi.org/project/package-name/
# 6. Test installation from TestPyPI
uv pip install --index-url https://test.pypi.org/simple/ package-name
# 7. If all looks good, upload to production PyPI
uv run --with twine twine upload dist/*
Test Markdown rendering locally
# Install grip (GitHub README previewer)
uv tool install grip
# Preview README.md
uvx grip README.md
# Opens browser at http://localhost:6419
Test reStructuredText rendering locally
# Convert RST to HTML for preview
uv run --with docutils rst2html.py README.rst README.html
# Open in browser
xdg-open README.html # Linux
open README.html # macOS
Validate RST syntax
# Check for RST errors
uv run --with docutils rst2html.py README.rst /dev/null
# Only shows errors/warnings, no output file
Issue: Sphinx roles not rendering
❌ WRONG (will fail on PyPI):
See :py:func:`package.function` for details.
Use :ref:`my-label` for more information.
✓ CORRECT (PyPI-compatible):
See ``package.function()`` for details.
Use `my-label`_ for more information.
.. _my-label: https://docs.example.com/section
Issue: Code block indentation
❌ WRONG:
.. code-block:: python
import package # No blank line, incorrect indent
✓ CORRECT:
.. code-block:: python
import package # Blank line after directive, proper indent
package.run()
Issue: Link definition spacing
❌ WRONG:
`Documentation`_
.. _Documentation: https://example.com # Too close
✓ CORRECT:
`Documentation`_
.. _Documentation: https://example.com # Blank line before
Issue: Code fence language specification
❌ WRONG:
```
import package # No language specified
```
✓ CORRECT:
```python
import package
```
Issue: Heading hierarchy
❌ WRONG:
# Title
### Subsection # Skipped ##
✓ CORRECT:
# Title
## Section
### Subsection
Issue: Platform-specific line endings
# Convert to Unix line endings (LF)
dos2unix README.md # or README.rst
# Or using Python
uv run python -c "
import sys
with open('README.md', 'r') as f:
content = f.read()
with open('README.md', 'w', newline='\n') as f:
f.write(content)
"
Issue: Rendering differences GitHub vs PyPI
See reference files for complete examples:
references/markdown-template.md - Modern Markdown README templatereferences/rst-template.rst - reStructuredText README templatereferences/sphinx-readme-example.md - Using sphinx-readme extensionSkills to activate:
uv - For Python project and package managementhatchling - For build backend configurationgitlab-skill - For GitLab Flavored Markdown featuresExternal tools:
twine - README validation and PyPI publishingsphinx-readme - Generate PyPI-compatible RST from Sphinxgrip - Preview Markdown as GitHub renders itdocutils - Validate and convert reStructuredTextpandoc - Convert between Markdown and RSTConsult ../python3-development/references/python3-standards.md when applying shared architecture, typing, testing, or CLI rules; full standards, graphs, and amendment process are documented there.
Before finalizing a README:
twine checktwine check before uploadingsphinx-readme for Sphinx-based projects