# 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
```bash
git clone https://github.com/yourusername/ts-sphinx.git
cd ts-sphinx
uv sync
```
## Configuration
Add the extension to your Sphinx `conf.py`:
```python
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:
```rst
.. ts:autoclass:: MyClass
:members:
:undoc-members:
:show-inheritance:
```
#### `ts:autointerface`
Automatically document a TypeScript interface:
```rst
.. ts:autointerface:: MyInterface
:members:
:undoc-members:
```
#### `ts:autoenum`
Automatically document a TypeScript enum:
```rst
.. ts:autoenum:: MyEnum
:members:
:undoc-members:
```
#### `ts:autodata`
Automatically document TypeScript variables and constants:
```rst
.. 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:
```rst
: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:
```python
# 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-ts",
"maintainer": "Thomas Carroll",
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "sphinx, typescript, documentation, autodoc, tree-sitter, jsdoc, api-documentation",
"author": "Thomas Carroll",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9f/d7/78389e4526ae2c4772cc0c4900b3499de5f0b4f156d7a0c506e978099d3a/sphinx_ts-0.4.0.tar.gz",
"platform": null,
"description": "# TypeScript Sphinx Extension\n\nA Sphinx extension that provides autodoc-like functionality for TypeScript files\nusing Tree-sitter for parsing. This extension allows you to automatically\ngenerate documentation for TypeScript classes, interfaces, and variables from\nyour source code, similar to Python's autodoc.\n\n## Features\n\n- **Automatic Documentation Generation**: Extract documentation from TypeScript source files\n- **JSDoc Support**: Parse and render JSDoc comments as reStructuredText\n- **Multiple Directives**: Support for `ts:autoclass`, `ts:autointerface`, `ts:autoenum`, and `ts:autodata`\n- **Tree-sitter Parsing**: Robust TypeScript parsing using Tree-sitter\n- **Sphinx Integration**: Full integration with Sphinx's cross-referencing and indexing systems\n- **Type Information**: Display TypeScript type annotations and signatures\n\n## Installation\n\nThis project uses uv for package management.\n\n### Install from Source\n\n```bash\ngit clone https://github.com/yourusername/ts-sphinx.git\ncd ts-sphinx\nuv sync\n```\n\n## Configuration\n\nAdd the extension to your Sphinx `conf.py`:\n\n```python\nextensions = [\n 'sphinx_ts',\n # other extensions...\n]\n\n# TypeScript Sphinx configuration\nsphinx_ts_src_dirs = ['src', 'lib'] # Directories to scan for TypeScript files\nsphinx_ts_exclude_patterns = ['**/*.test.ts', '**/*.spec.ts'] # Files to exclude\nsphinx_ts_include_private = False # Include private members\nsphinx_ts_include_inherited = True # Include inherited members\n\n# Source linking configuration\nsphinx_ts_show_source_links = True # Show links to source code\nsphinx_ts_source_base_url = 'https://github.com/yourusername/yourproject' # Base URL for source links\nsphinx_ts_source_branch = 'main' # Git branch to link to\n# Or use a custom URL template:\n# sphinx_ts_source_url_template = 'https://github.com/user/repo/blob/{branch}/{path}'\n```\n\n## Usage\n\n### Available Directives\n\n#### `ts:autoclass`\n\nAutomatically document a TypeScript class:\n\n```rst\n.. ts:autoclass:: MyClass\n :members:\n :undoc-members:\n :show-inheritance:\n```\n\n#### `ts:autointerface`\n\nAutomatically document a TypeScript interface:\n\n```rst\n.. ts:autointerface:: MyInterface\n :members:\n :undoc-members:\n```\n\n#### `ts:autoenum`\n\nAutomatically document a TypeScript enum:\n\n```rst\n.. ts:autoenum:: MyEnum\n :members:\n :undoc-members:\n```\n\n#### `ts:autodata`\n\nAutomatically document TypeScript variables and constants:\n\n```rst\n.. ts:autodata:: myVariable\n.. ts:autodata:: MY_CONSTANT\n```\n\n### Directive Options\n\nAll auto-directives support the following options:\n\n- `:members:` - Include all members\n- `:undoc-members:` - Include members without documentation\n- `:show-inheritance:` - Show inheritance relationships (classes only)\n- `:member-order:` - Order of members (`alphabetical`, `groupwise`, or `bysource`)\n- `:exclude-members:` - Comma-separated list of members to exclude\n- `:private-members:` - Include private members\n- `:special-members:` - Include special members\n- `:no-index:` - Don't add to the general index\n\n### Cross-References\n\nThe extension provides several roles for cross-referencing:\n\n```rst\n:ts:class:`MyClass`\n:ts:interface:`MyInterface`\n:ts:enum:`MyEnum`\n:ts:prop:`MyClass.myProperty`\n```\n\n\n## JSDoc Support\n\nThe extension supports standard JSDoc tags:\n\n- `@param {type} name description` - Parameter documentation\n- `@returns description` or `@return description` - Return value documentation\n- `@example` - Code examples\n- `@since version` - Version information\n- `@deprecated message` - Deprecation notices\n- Custom tags are also preserved\n\n## Advanced Features\n\n### Type Information\n\nThe extension automatically extracts and displays:\n\n- Parameter types and default values\n- Return types\n- Property types\n- Generic type parameters\n- Union and intersection types\n\n### Inheritance\n\nFor classes, the extension shows:\n\n- Base class inheritance\n- Implemented interfaces\n- Inherited methods and properties\n\n### Source Links\n\nEach documented item includes a reference to its source file for easy navigation. Configure source linking with:\n\n```python\n# In conf.py\nsphinx_ts_show_source_links = True # Enable source links (default: True)\nsphinx_ts_source_base_url = 'https://github.com/yourusername/yourproject' # Base repository URL\nsphinx_ts_source_branch = 'main' # Git branch to link to (default: 'main')\n\n# Or use a custom URL template for more control:\nsphinx_ts_source_url_template = 'https://github.com/{user}/{repo}/blob/{branch}/{path}'\n```\n\nSource links will automatically include line numbers when available, linking directly to the specific location where each class, interface, enum, or function is defined.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Sphinx extension for TypeScript documentation using Tree-sitter",
"version": "0.4.0",
"project_urls": {
"Bug Reports": "https://github.com/snus-kin/sphinx-ts/issues",
"Changelog": "https://github.com/snus-kin/sphinx-ts/releases",
"Documentation": "https://sphinx-ts.readthedocs.io",
"Homepage": "https://github.com/snus-kin/sphinx-ts",
"Repository": "https://github.com/snus-kin/sphinx-ts"
},
"split_keywords": [
"sphinx",
" typescript",
" documentation",
" autodoc",
" tree-sitter",
" jsdoc",
" api-documentation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "185d092c106f4a102e1e85cb9873fd82848bfc63c9a6b309a81d4c466e4bd525",
"md5": "333f0d476f0d60ddec936beed2084a39",
"sha256": "06c980427a27dddf01aedfaa4b09679efb1b9fc99a171176b7a7e3a90cfbb22a"
},
"downloads": -1,
"filename": "sphinx_ts-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "333f0d476f0d60ddec936beed2084a39",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 38075,
"upload_time": "2025-09-07T21:15:38",
"upload_time_iso_8601": "2025-09-07T21:15:38.589220Z",
"url": "https://files.pythonhosted.org/packages/18/5d/092c106f4a102e1e85cb9873fd82848bfc63c9a6b309a81d4c466e4bd525/sphinx_ts-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9fd778389e4526ae2c4772cc0c4900b3499de5f0b4f156d7a0c506e978099d3a",
"md5": "dcd47ca63df5d2507d8adcafc8a0af4d",
"sha256": "27e67e5b8f530c42fa87082c47b62a58fccf5ef1dc1c6ca8a1044806f987f036"
},
"downloads": -1,
"filename": "sphinx_ts-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "dcd47ca63df5d2507d8adcafc8a0af4d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 30562,
"upload_time": "2025-09-07T21:15:40",
"upload_time_iso_8601": "2025-09-07T21:15:40.257062Z",
"url": "https://files.pythonhosted.org/packages/9f/d7/78389e4526ae2c4772cc0c4900b3499de5f0b4f156d7a0c506e978099d3a/sphinx_ts-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 21:15:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "snus-kin",
"github_project": "sphinx-ts",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-ts"
}
JSON
