| Name | sphinx-vb-domain JSON |
| Version |
0.8.2
JSON |
| download |
| home_page | None |
| Summary | Sphinx extension to handle Visual Basic Domain. |
| upload_time | 2025-08-19 15:54:06 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
extension
sphinx
vb
visual basic
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# sphinx-vb-domain
[≫日本語版](https://github.com/satamame/sphinx-vb-domain/blob/main/README_ja.md)
## Overview
Sphinx extension to handle Visual Basic function directive, and also create the directives from document comments in VB source code.
This project is really experimental. Only features below are working but without any assurance.
## Installation
### pip
```
pip install sphinx-vb-domain
```
### rye
```
rye add --dev sphinx-vb-domain
```
## Usage
### conf.py
Add it to `extensions`.
```python
# conf.py
extensions = [
'sphinx_vb_domain',
]
```
### Function directive
For example.
```restructuredtext
.. vb:function:: Private Function getId(ByVal name As String, ByVal age As Integer) As Integer
:module: Module1
A simple private function.
:param name: Name
:type name: String
:param age: Age
:type age: Integer
:returns: Id
:rtype: Integer
Remarks here.
```
### Configuration
The following settings can be used in `conf.py`.
#### vb_add_function_labels
```python
vb_add_function_labels = False # Default: True
```
Setting to `False` disables adding target labels to function directives.
If you are using `sphinx.ext.autosectionlabel`, you may set this to `False`.
However, labels in `sphinx-vb-domain` take the form `{module_name}.{function_name}`, so if multiple modules have functions with the same name, you may take this feature.
#### vb_encode_invalid_labels
```python
vb_encode_invalid_labels = False # Default: True
```
If set to `False`, function names containing invalid characters for Sphinx target labels will not be hash-encoded.
This setting also applies to explicit labels added to module headings in Autodoc.
#### vb_add_docname_to_labels
```python
vb_add_docname_to_labels = True # Default: False
```
Setting to `True` adds labels to function directives in the form `{filepath}-{module_name}.{function_name}`, allowing functions with the same name in the same module across multiple files to be distinguished.
Directory delimiters in `{filepath}` part become `'-'`.
This setting also applies to explicit labels added to module headings in Autodoc.
#### vb_docname_label_delimiter
```python
vb_docname_label_delimiter = '__' # Default: '-'
```
`vb_add_docname_to_labels` sets the delimiter that appears after the directory/file names.
You must specify characters that are valid for Sphinx target labels.
This setting also applies to explicit labels added to module headings in Autodoc.
#### vb_autodoc_module_labels
```python
vb_autodoc_module_labels = True # Default: False
```
Setting to `True` adds explicit labels to module headings in Autodoc.
### Autodoc
To create document from VB document comments, following config is needed.
```python
# conf.py
vb_autodoc_paths = [
(vb_src_dir, page_path, page_title, notes),
]
```
- `vb_src_dir`
- Path to directory contains VB source, relative from conf.py (e.g. '../../macros').
- `page_path`
- Path to reST file tobe created, relative from Sphinx source directory (e.g. 'modules' will create 'modules.rst').
- `page_title`
- Title (level-1 headline) added to e.g. modules.rst.
- `notes`
- Optional dict to add notes to below targets (dict keys).
- `'__page__'`: Note to be added under page title.
- `'<Module name>'`: Note to be added under the module's title.
- `'<Module name>.<Function name>'`: Note to be added under the function's directive.
```python
# Example
# Note: Values can be reST, but you should not use headlines.
notes = {
'__page__': 'This is note for the page.',
'Module1': 'This is note for Module1.',
'Module1.MyFunction': 'This is note for MyFunction.',
}
```
Then, run sphinx-build with `-D vb_autodoc=1` parameter.
In file at `page_path` (e.g. 'modules.rst'), Module (level-2 headline) is created per vb file in `vb_src_dir`, and function directives under the Modules.
#### Notes from template
You can create a template in reST and convert it to dict as notes.
```restructuredtext
__page__
========
This is note for the page.
Module1
-------
This is note for Module1.
Module1.MyFunction
~~~~~~~~~~~~~~~~~~
This is note for MyFunction.
```
Put it in _templates folder, then call `notes_from_template()` function.
```python
# conf.py
from sphinx_vb_domain.utils import notes_from_template
notes = notes_from_template('notes.rst')
vb_autodoc_paths = [
(vb_src_dir, page_path, page_title, notes),
]
```
### Cross-references
When function directives are rendered, they come with a headline so that the directives appear in toctree.
Also, when `vb_add_function_labels` is set to `True` (Default), the headline will be a cross-reference target.
#### reStructuredText
```restructuredtext
* :vb:function:`module_name.function_name`
* :any:`module_name.function_name`
* :any:`Link text <module_name.function_name>`
```
#### MyST
```markdown
- {vb:function}`module_name.function_name`
- <project:#module_name.function_name>
- [Link text](#module_name.function_name)
```
## Known issues
- Function directive always rendered in Japanese like follows.
```
Private Function getId(ByVal name As String, ByVal age As Integer) As Integer
A simple private function.
パラメータ: ・name (String) -- Name
・age (Integer) -- Age
戻り値: Id
戻り値の型: Integer
Remarks here.
```
- You can change `doc_field_types` definition of `VBFunction` class.
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-vb-domain",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "extension, sphinx, vb, visual basic",
"author": null,
"author_email": "satamame <satamame@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/29/7b/ae82ca222db39f8b85e5050e013fa1b231fba02623c9e55e678eb20995cc/sphinx_vb_domain-0.8.2.tar.gz",
"platform": null,
"description": "# sphinx-vb-domain\n\n[\u226b\u65e5\u672c\u8a9e\u7248](https://github.com/satamame/sphinx-vb-domain/blob/main/README_ja.md)\n\n## Overview\n\nSphinx extension to handle Visual Basic function directive, and also create the directives from document comments in VB source code.\n\nThis project is really experimental. Only features below are working but without any assurance.\n\n## Installation\n\n### pip\n\n```\npip install sphinx-vb-domain\n```\n\n### rye\n\n```\nrye add --dev sphinx-vb-domain\n```\n\n## Usage\n\n### conf.py\n\nAdd it to `extensions`.\n\n```python\n# conf.py\n\nextensions = [\n 'sphinx_vb_domain',\n]\n```\n\n### Function directive\n\nFor example.\n\n```restructuredtext\n.. vb:function:: Private Function getId(ByVal name As String, ByVal age As Integer) As Integer\n :module: Module1\n\n A simple private function.\n\n :param name: Name\n :type name: String\n :param age: Age\n :type age: Integer\n :returns: Id\n :rtype: Integer\n\n Remarks here.\n```\n\n### Configuration\n\nThe following settings can be used in `conf.py`.\n\n#### vb_add_function_labels\n\n```python\nvb_add_function_labels = False # Default: True\n```\n\nSetting to `False` disables adding target labels to function directives. \nIf you are using `sphinx.ext.autosectionlabel`, you may set this to `False`. \nHowever, labels in `sphinx-vb-domain` take the form `{module_name}.{function_name}`, so if multiple modules have functions with the same name, you may take this feature.\n\n#### vb_encode_invalid_labels\n\n```python\nvb_encode_invalid_labels = False # Default: True\n```\n\nIf set to `False`, function names containing invalid characters for Sphinx target labels will not be hash-encoded. \nThis setting also applies to explicit labels added to module headings in Autodoc.\n\n#### vb_add_docname_to_labels\n\n```python\nvb_add_docname_to_labels = True # Default: False\n```\n\nSetting to `True` adds labels to function directives in the form `{filepath}-{module_name}.{function_name}`, allowing functions with the same name in the same module across multiple files to be distinguished. \nDirectory delimiters in `{filepath}` part become `'-'`. \nThis setting also applies to explicit labels added to module headings in Autodoc.\n\n#### vb_docname_label_delimiter\n\n```python\nvb_docname_label_delimiter = '__' # Default: '-'\n```\n\n`vb_add_docname_to_labels` sets the delimiter that appears after the directory/file names. \nYou must specify characters that are valid for Sphinx target labels. \nThis setting also applies to explicit labels added to module headings in Autodoc.\n\n#### vb_autodoc_module_labels\n\n```python\nvb_autodoc_module_labels = True # Default: False\n```\n\nSetting to `True` adds explicit labels to module headings in Autodoc.\n\n### Autodoc\n\nTo create document from VB document comments, following config is needed.\n\n```python\n# conf.py\n\nvb_autodoc_paths = [\n (vb_src_dir, page_path, page_title, notes),\n]\n```\n\n- `vb_src_dir`\n - Path to directory contains VB source, relative from conf.py (e.g. '../../macros').\n- `page_path`\n - Path to reST file tobe created, relative from Sphinx source directory (e.g. 'modules' will create 'modules.rst').\n- `page_title`\n - Title (level-1 headline) added to e.g. modules.rst.\n- `notes`\n - Optional dict to add notes to below targets (dict keys).\n - `'__page__'`: Note to be added under page title.\n - `'<Module name>'`: Note to be added under the module's title.\n - `'<Module name>.<Function name>'`: Note to be added under the function's directive.\n ```python\n # Example\n # Note: Values can be reST, but you should not use headlines.\n notes = {\n '__page__': 'This is note for the page.',\n 'Module1': 'This is note for Module1.',\n 'Module1.MyFunction': 'This is note for MyFunction.',\n }\n ```\n\nThen, run sphinx-build with `-D vb_autodoc=1` parameter.\n\nIn file at `page_path` (e.g. 'modules.rst'), Module (level-2 headline) is created per vb file in `vb_src_dir`, and function directives under the Modules.\n\n#### Notes from template\n\nYou can create a template in reST and convert it to dict as notes.\n\n```restructuredtext\n__page__\n========\n\nThis is note for the page.\n\nModule1\n-------\n\nThis is note for Module1.\n\nModule1.MyFunction\n~~~~~~~~~~~~~~~~~~\n\nThis is note for MyFunction.\n```\n\nPut it in _templates folder, then call `notes_from_template()` function.\n\n```python\n# conf.py\nfrom sphinx_vb_domain.utils import notes_from_template\n\nnotes = notes_from_template('notes.rst')\n\nvb_autodoc_paths = [\n (vb_src_dir, page_path, page_title, notes),\n]\n```\n\n### Cross-references\n\nWhen function directives are rendered, they come with a headline so that the directives appear in toctree. \nAlso, when `vb_add_function_labels` is set to `True` (Default), the headline will be a cross-reference target.\n\n#### reStructuredText\n\n```restructuredtext\n* :vb:function:`module_name.function_name`\n* :any:`module_name.function_name`\n* :any:`Link text <module_name.function_name>`\n```\n\n#### MyST\n\n```markdown\n- {vb:function}`module_name.function_name`\n- <project:#module_name.function_name>\n- [Link text](#module_name.function_name)\n```\n\n## Known issues\n\n- Function directive always rendered in Japanese like follows.\n ```\n Private Function getId(ByVal name As String, ByVal age As Integer) As Integer\n \n A simple private function.\n\n \u30d1\u30e9\u30e1\u30fc\u30bf: \u30fbname (String) -- Name\n \u30fbage (Integer) -- Age\n \u623b\u308a\u5024: Id\n \u623b\u308a\u5024\u306e\u578b: Integer\n\n Remarks here.\n ```\n - You can change `doc_field_types` definition of `VBFunction` class.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Sphinx extension to handle Visual Basic Domain.",
"version": "0.8.2",
"project_urls": {
"Changelog": "https://github.com/satamame/sphinx-vb-domain/releases",
"Homepage": "https://github.com/satamame/sphinx-vb-domain",
"Issues": "https://github.com/satamame/sphinx-vb-domain/issues",
"Repository": "https://github.com/satamame/sphinx-vb-domain.git"
},
"split_keywords": [
"extension",
" sphinx",
" vb",
" visual basic"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f84685c37e3a949c52e85f8bd5c49c1ff88977d2c9f2faacd0afdaef0588b919",
"md5": "aef8373cdd48ba5356c7a10eb1415332",
"sha256": "cb187bc2901abc669f0de5eb77c0407d8fb49097f620442c1eaff9caeeb587ff"
},
"downloads": -1,
"filename": "sphinx_vb_domain-0.8.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aef8373cdd48ba5356c7a10eb1415332",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13181,
"upload_time": "2025-08-19T15:54:05",
"upload_time_iso_8601": "2025-08-19T15:54:05.050958Z",
"url": "https://files.pythonhosted.org/packages/f8/46/85c37e3a949c52e85f8bd5c49c1ff88977d2c9f2faacd0afdaef0588b919/sphinx_vb_domain-0.8.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "297bae82ca222db39f8b85e5050e013fa1b231fba02623c9e55e678eb20995cc",
"md5": "abf3a6badddaad3f61f8d14af9e5ef3a",
"sha256": "898882c1b71bab553be1ff143438c6c7c686def3e1da13ebfd01265709a33574"
},
"downloads": -1,
"filename": "sphinx_vb_domain-0.8.2.tar.gz",
"has_sig": false,
"md5_digest": "abf3a6badddaad3f61f8d14af9e5ef3a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 824102,
"upload_time": "2025-08-19T15:54:06",
"upload_time_iso_8601": "2025-08-19T15:54:06.631396Z",
"url": "https://files.pythonhosted.org/packages/29/7b/ae82ca222db39f8b85e5050e013fa1b231fba02623c9e55e678eb20995cc/sphinx_vb_domain-0.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 15:54:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "satamame",
"github_project": "sphinx-vb-domain",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sphinx-vb-domain"
}
