sphinx-ts 0.4.0

Sphinx extension for TypeScript documentation using Tree-sitter

TypeScript Sphinx Extension

A Sphinx extension that provides autodoc-like functionality for TypeScript files using Tree-sitter for parsing. This extension allows you to automatically generate documentation for TypeScript classes, interfaces, and variables from your source code, similar to Python's autodoc.

Features

• Automatic Documentation Generation: Extract documentation from TypeScript source files
• JSDoc Support: Parse and render JSDoc comments as reStructuredText
• Multiple Directives: Support for ts:autoclass, ts:autointerface, ts:autoenum, and ts:autodata
• Tree-sitter Parsing: Robust TypeScript parsing using Tree-sitter
• Sphinx Integration: Full integration with Sphinx's cross-referencing and indexing systems
• Type Information: Display TypeScript type annotations and signatures

Installation

This project uses uv for package management.

Install from Source

git clone https://github.com/yourusername/ts-sphinx.git
cd ts-sphinx
uv sync

Configuration

Add the extension to your Sphinx conf.py:

extensions = [
    'sphinx_ts',
    # other extensions...
]

# TypeScript Sphinx configuration
sphinx_ts_src_dirs = ['src', 'lib']  # Directories to scan for TypeScript files
sphinx_ts_exclude_patterns = ['**/*.test.ts', '**/*.spec.ts']  # Files to exclude
sphinx_ts_include_private = False  # Include private members
sphinx_ts_include_inherited = True  # Include inherited members

# Source linking configuration
sphinx_ts_show_source_links = True  # Show links to source code
sphinx_ts_source_base_url = 'https://github.com/yourusername/yourproject'  # Base URL for source links
sphinx_ts_source_branch = 'main'  # Git branch to link to
# Or use a custom URL template:
# sphinx_ts_source_url_template = 'https://github.com/user/repo/blob/{branch}/{path}'

Usage

Available Directives

ts:autoclass

Automatically document a TypeScript class:

.. ts:autoclass:: MyClass
   :members:
   :undoc-members:
   :show-inheritance:

ts:autointerface

Automatically document a TypeScript interface:

.. ts:autointerface:: MyInterface
   :members:
   :undoc-members:

ts:autoenum

Automatically document a TypeScript enum:

.. ts:autoenum:: MyEnum
   :members:
   :undoc-members:

ts:autodata

Automatically document TypeScript variables and constants:

.. ts:autodata:: myVariable
.. ts:autodata:: MY_CONSTANT

Directive Options

All auto-directives support the following options:

• :members: - Include all members
• :undoc-members: - Include members without documentation
• :show-inheritance: - Show inheritance relationships (classes only)
• :member-order: - Order of members (alphabetical, groupwise, or bysource)
• :exclude-members: - Comma-separated list of members to exclude
• :private-members: - Include private members
• :special-members: - Include special members
• :no-index: - Don't add to the general index

Cross-References

The extension provides several roles for cross-referencing:

:ts:class:`MyClass`
:ts:interface:`MyInterface`
:ts:enum:`MyEnum`
:ts:prop:`MyClass.myProperty`

JSDoc Support

The extension supports standard JSDoc tags:

• @param {type} name description - Parameter documentation
• @returns description or @return description - Return value documentation
• @example - Code examples
• @since version - Version information
• @deprecated message - Deprecation notices
• Custom tags are also preserved

Advanced Features

Type Information

The extension automatically extracts and displays:

• Parameter types and default values
• Return types
• Property types
• Generic type parameters
• Union and intersection types

Inheritance

For classes, the extension shows:

• Base class inheritance
• Implemented interfaces
• Inherited methods and properties

Source Links

Each documented item includes a reference to its source file for easy navigation. Configure source linking with:

# In conf.py
sphinx_ts_show_source_links = True  # Enable source links (default: True)
sphinx_ts_source_base_url = 'https://github.com/yourusername/yourproject'  # Base repository URL
sphinx_ts_source_branch = 'main'  # Git branch to link to (default: 'main')

# Or use a custom URL template for more control:
sphinx_ts_source_url_template = 'https://github.com/{user}/{repo}/blob/{branch}/{path}'

Source links will automatically include line numbers when available, linking directly to the specific location where each class, interface, enum, or function is defined.