| Name | sphinx-vb-domain JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | None |
| Summary | Sphinx extension to handle Visual Basic Domain. |
| upload_time | 2025-01-13 10:34:27 |
| 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
## 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.
```
### Autodoc
To creade document from VB document comments, following config is needed.
```python
# conf.py
vb_autodoc_paths = [
('vb-src-dir', 'page-path', 'page-title'),
]
```
- `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.
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 files in 'vb-src-dir', and function directives under the Modules.
### Cross-references
When function directives are rendered, they come with a headline so that the directives appear in toctree.
Also, 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)
```
> [!NOTE]
> `module_name` and `function_name` are encoded if they contain characters invalid as target 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/72/81/b87cf47f0b2bc12743a1bfcf4b4b74985086e24da898e9abf8886e244d05/sphinx_vb_domain-0.3.0.tar.gz",
"platform": null,
"description": "# sphinx-vb-domain\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### Autodoc\n\nTo creade 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'),\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\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 files in 'vb-src-dir', and function directives under the Modules.\n\n### Cross-references\n\nWhen function directives are rendered, they come with a headline so that the directives appear in toctree. \nAlso, 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> [!NOTE]\n> `module_name` and `function_name` are encoded if they contain characters invalid as target name.\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.3.0",
"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": "eafa9fc98b0b7684907ccc58ea7a5c4d195398a4f3b6f0fe4afb254788154dfd",
"md5": "e2fcf8c0a1694bc09f24ad7eb6a00f8b",
"sha256": "ca03e91cdb7c6d1e9c93cea20e9191f3158f0b7658c86e0726b7b3e60bd57e01"
},
"downloads": -1,
"filename": "sphinx_vb_domain-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2fcf8c0a1694bc09f24ad7eb6a00f8b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9525,
"upload_time": "2025-01-13T10:34:24",
"upload_time_iso_8601": "2025-01-13T10:34:24.141572Z",
"url": "https://files.pythonhosted.org/packages/ea/fa/9fc98b0b7684907ccc58ea7a5c4d195398a4f3b6f0fe4afb254788154dfd/sphinx_vb_domain-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7281b87cf47f0b2bc12743a1bfcf4b4b74985086e24da898e9abf8886e244d05",
"md5": "76a282a00620759fa22443129a1db8fb",
"sha256": "0da91348845fb1e0800a371ec50ac6c9956890849001023311a0b4f2eee20b98"
},
"downloads": -1,
"filename": "sphinx_vb_domain-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "76a282a00620759fa22443129a1db8fb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 816675,
"upload_time": "2025-01-13T10:34:27",
"upload_time_iso_8601": "2025-01-13T10:34:27.328193Z",
"url": "https://files.pythonhosted.org/packages/72/81/b87cf47f0b2bc12743a1bfcf4b4b74985086e24da898e9abf8886e244d05/sphinx_vb_domain-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-13 10:34:27",
"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"
}
