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.
- 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, andts: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
This project uses uv for package management.
git clone https://github.com/yourusername/ts-sphinx.git
cd ts-sphinx
uv syncAdd 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}'Automatically document a TypeScript class:
.. ts:autoclass:: MyClass
:members:
:undoc-members:
:show-inheritance:Automatically document a TypeScript interface:
.. ts:autointerface:: MyInterface
:members:
:undoc-members:Automatically document a TypeScript enum:
.. ts:autoenum:: MyEnum
:members:
:undoc-members:Automatically document TypeScript variables and constants:
.. ts:autodata:: myVariable
.. ts:autodata:: MY_CONSTANTAll 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, orbysource):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
The extension provides several roles for cross-referencing:
:ts:class:`MyClass`
:ts:interface:`MyInterface`
:ts:enum:`MyEnum`
:ts:prop:`MyClass.myProperty`The extension supports standard JSDoc tags:
@param {type} name description- Parameter documentation@returns descriptionor@return description- Return value documentation@example- Code examples@since version- Version information@deprecated message- Deprecation notices- Custom tags are also preserved
The extension automatically extracts and displays:
- Parameter types and default values
- Return types
- Property types
- Generic type parameters
- Union and intersection types
For classes, the extension shows:
- Base class inheritance
- Implemented interfaces
- Inherited methods and properties
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.