| Name | docblock JSON |
| Version |
0.1.5
JSON |
| download |
| home_page | https://github.com/N-Wouda/docblock |
| Summary | Reads and parses documentation from header files in pure Python. |
| upload_time | 2024-02-02 23:33:03 |
| maintainer | |
| docs_url | None |
| author | Niels Wouda |
| requires_python | >=3.8,<4.0 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://badge.fury.io/py/docblock)
[](https://github.com/N-Wouda/docblock/actions/workflows/CI.yaml)
[](https://codecov.io/gh/N-Wouda/docblock)
The `docblock` package reads and parses documentation from C++ header files.
It should also work out of the box for C header files, but that is currently untested.
It is opinionated and explicitly does *not* cover all edge cases of the C++ grammar, but hopes to provide sufficient utility for most use cases.
The package assumes documentation blocks are formatted using C-style comments, as follows:
```cpp
/**
* Text
*/
void func();
```
That is, the documentation block starts with `/*` or `/**`, and ends with `*/`.
Any starting `*` on documentation lines in the block are allowed, but not required unless you care about significant whitespace.
> To avoid parsing issues, non-documentation block comments SHOULD NOT use C-style comments.
The `docblock` package is a pure Python package and depends only on `pyparsing`.
It can be installed as
```shell
pip install docblock
```
## Example usage
Consider the following header file `test.h`:
```cpp
// test.h
/**
* Test namespace.
*/
namespace test
{
class Test
{
public:
/**
* First constructor
*/
Test(int x);
/**
* Second constructor
*/
Test(int x, int y);
/**
* A method.
*/
void aMethod() const;
};
}; // namespace test
```
This file may be parsed as:
```python
from docblock import parse_file
res = parse_file("test.h")
```
Now, `res` contains:
```python
>>> print(res)
{
'test': ['Test namespace.'],
'test::Test::Test': ['First constructor', 'Second constructor'],
'test::Test::aMethod': ['A method.']
}
```
Observe that `docblock` understands scoping, and returns docstrings using qualified names.
For overloads, multiple docstrings are returned: one for each documented overload.
## Why `docblock`?
Parsing documentation from header files is common practice to generate documentation, particularly in mixed-language projects where the C++ components are intended to be used from another language.
One tool that simplifies this for C++-to-Python is [pybind11_mkdoc](https://github.com/pybind/pybind11_mkdoc).
That tool, however, relies on clang and the LLVM project to parse C++ documentation blocks: great if you're already using clang, but very heavy-handed if you do not.
This is where `docblock` comes in: it is a pure Python package that does not aim to parse all of C++'s grammar, but only extracts the documentation block's content and the function point it documents.
That is far easier to implement (not requiring a full compiler), but does mean it will very likely not parse all documentation blocks correctly.
Feel free to open an issue if you have an example that is not parsed correctly by `docblock`.
Raw data
{
"_id": null,
"home_page": "https://github.com/N-Wouda/docblock",
"name": "docblock",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Niels Wouda",
"author_email": "nielswouda@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a5/eb/ae8005c16155abadde8e986747546ce8c00992d2210072f2d86f484b479d/docblock-0.1.5.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/docblock)\n[](https://github.com/N-Wouda/docblock/actions/workflows/CI.yaml)\n[](https://codecov.io/gh/N-Wouda/docblock)\n\nThe `docblock` package reads and parses documentation from C++ header files.\nIt should also work out of the box for C header files, but that is currently untested.\nIt is opinionated and explicitly does *not* cover all edge cases of the C++ grammar, but hopes to provide sufficient utility for most use cases.\nThe package assumes documentation blocks are formatted using C-style comments, as follows:\n```cpp\n/**\n * Text\n */\nvoid func();\n```\nThat is, the documentation block starts with `/*` or `/**`, and ends with `*/`.\nAny starting `*` on documentation lines in the block are allowed, but not required unless you care about significant whitespace.\n> To avoid parsing issues, non-documentation block comments SHOULD NOT use C-style comments. \n\nThe `docblock` package is a pure Python package and depends only on `pyparsing`.\nIt can be installed as\n```shell\npip install docblock\n``` \n\n## Example usage\n\nConsider the following header file `test.h`:\n```cpp\n// test.h\n\n/**\n * Test namespace.\n */\nnamespace test\n{\nclass Test\n{\npublic:\n /**\n * First constructor\n */\n Test(int x);\n\n /**\n * Second constructor\n */\n Test(int x, int y);\n\n /**\n * A method.\n */\n void aMethod() const;\n};\n}; // namespace test\n```\nThis file may be parsed as:\n```python\nfrom docblock import parse_file\n\nres = parse_file(\"test.h\")\n```\nNow, `res` contains:\n```python\n>>> print(res)\n{\n 'test': ['Test namespace.'],\n 'test::Test::Test': ['First constructor', 'Second constructor'],\n 'test::Test::aMethod': ['A method.']\n}\n```\nObserve that `docblock` understands scoping, and returns docstrings using qualified names.\nFor overloads, multiple docstrings are returned: one for each documented overload.\n\n## Why `docblock`?\n\nParsing documentation from header files is common practice to generate documentation, particularly in mixed-language projects where the C++ components are intended to be used from another language.\nOne tool that simplifies this for C++-to-Python is [pybind11_mkdoc](https://github.com/pybind/pybind11_mkdoc).\nThat tool, however, relies on clang and the LLVM project to parse C++ documentation blocks: great if you're already using clang, but very heavy-handed if you do not.\n\nThis is where `docblock` comes in: it is a pure Python package that does not aim to parse all of C++'s grammar, but only extracts the documentation block's content and the function point it documents.\nThat is far easier to implement (not requiring a full compiler), but does mean it will very likely not parse all documentation blocks correctly.\nFeel free to open an issue if you have an example that is not parsed correctly by `docblock`.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Reads and parses documentation from header files in pure Python.",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/N-Wouda/docblock",
"Repository": "https://github.com/N-Wouda/docblock",
"Tracker": "https://github.com/N-Wouda/docblock/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5a589df3ec99e3dacc11847b2ff63bceb5b5c9a4ad01d0eff357e8370624ce15",
"md5": "e338461ad0ac6a14909bd5dc667883ac",
"sha256": "b11e647c2be6865507ea4e48dd7600bb351e013a3bbeaea971a17eb725745457"
},
"downloads": -1,
"filename": "docblock-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e338461ad0ac6a14909bd5dc667883ac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 7102,
"upload_time": "2024-02-02T23:33:02",
"upload_time_iso_8601": "2024-02-02T23:33:02.015470Z",
"url": "https://files.pythonhosted.org/packages/5a/58/9df3ec99e3dacc11847b2ff63bceb5b5c9a4ad01d0eff357e8370624ce15/docblock-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a5ebae8005c16155abadde8e986747546ce8c00992d2210072f2d86f484b479d",
"md5": "8c5d22556072efdd24bf2ce5187730e4",
"sha256": "041ea41c2fb15c11be0540e80f11ec6d1e1a21c8305951b470c3051105237b2c"
},
"downloads": -1,
"filename": "docblock-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "8c5d22556072efdd24bf2ce5187730e4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 5531,
"upload_time": "2024-02-02T23:33:03",
"upload_time_iso_8601": "2024-02-02T23:33:03.705192Z",
"url": "https://files.pythonhosted.org/packages/a5/eb/ae8005c16155abadde8e986747546ce8c00992d2210072f2d86f484b479d/docblock-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-02 23:33:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "N-Wouda",
"github_project": "docblock",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "docblock"
}
