| Name | foliantcontrib.dbmldoc JSON |
| Version |
0.3.4
JSON |
| download |
| home_page | |
| Summary | Documentation generator for DBML specification format |
| upload_time | 2023-06-15 17:27:52 |
| maintainer | |
| docs_url | None |
| author | Daniil Minukhin |
| requires_python | |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://pypi.org/project/foliantcontrib.dbmldoc/) [](https://github.com/foliant-docs/foliantcontrib.dbmldoc)
# DBML Docs Generator for Foliant
This preprocessor generates Markdown documentation from [DBML](https://www.dbml.org/) specification files . It uses [PyDBML](https://github.com/Vanderhoof/PyDBML) for parsing DBML syntax and [Jinja2](http://jinja.pocoo.org/) templating engine for generating Markdown.
## Installation
```bash
$ pip install foliantcontrib.dbmldoc
```
## Config
To enable the preprocessor, add `dbmldoc` to `preprocessors` section in the project config:
```yaml
preprocessors:
- dbmldoc
```
The preprocessor has a number of options:
```yaml
preprocessors:
- dbmldoc:
spec_url: http://localhost/scheme.dbml
spec_path: scheme.dbml
doc: true
scheme: true
template: dbml.j2
scheme_template: scheme.j2
```
`spec_url`
: URL to DBML spec file. If it is a list — preprocessor uses the first url which works.
`spec_path`
: Local path to DBML spec file (relative to project dir).
> If both url and path params are specified — preprocessor first tries to fetch spec from url, and only if that fails looks for the file on the local path.
`doc`
: If `true` — documentation will be generated. Set to `false` if you only want to draw a scheme of the database. Default `true`
`scheme`
: If `true` — the platuml code for database scheme will be generated. Default `true`
`template`
: Path to jinja-template for rendering the generated documentation. Path is relative to the project directory. If no template is specified preprocessor will use default template (and put it into project dir if it was missing). Default: `dbml.j2`
> Note that the default template may be outdated. Please check if everything works, and if needed — update the template.
`scheme_template`
: Path to jinja-template for generating planuml code for the database scheme. Path is relative to the project directory. If no template is specified preprocessor will use default template (and put it into project dir if it was missing). Default: `scheme.j2`
## Usage
Add a `<dbmldoc></dbmldoc>` tag at the position in the document where the generated documentation should be inserted:
```html
# Introduction
This document contains the automatically generated documentation of our Database schema.
<dbmldoc></dbmldoc>
```
Each time the preprocessor encounters the tag `<dbmldoc></dbmldoc>` it inserts the whole generated documentation text instead of it. The path or url to DBML spec file is taken from foliant.yml.
You can also override some parameters (or all of them) in the tag options:
```markdown
# Introduction
Introduction text for API documentation.
<dbmldoc spec_url="http://localhost/schema.dbml"
template="dbml.j2"
scheme="false">
</dbmldoc>
# Database scheme
And here goes a visual diagram of our database:
<dbmldoc doc="false" scheme="true">
</dbmldoc>
```
> Note that template path in tag is stated **relative to the markdown file**.
Tag parameters have the highest priority.
This way you can put your database description in one place and its diagram in the other (like in the example above). Or you can even have documentation from several different DBML spec files in one Foliant project.
## Customizing output
The output markdown is generated by the [Jinja2](http://jinja.pocoo.org/) template. Inside the template all data from the parsed DBML file is available under the `data` variable. It is in fact a `PyDBMLParseResults` object, as returned by [PyDBML](https://github.com/Vanderhoof/PyDBML) (see the docs to find out which attributes are available).
To customize the output create a template which suits your needs. Then supply the path to it in the `template` parameter. Same goes for the scheme template, which is defined in the `scheme_template` parameter.
If you wish to use the default template as a starting point, build the foliant project with `dbmldoc` preprocessor turned on. After the first build the default templates will appear in your foliant project dir under the names `dbml.j2` and `scheme.j2`.
Raw data
{
"_id": null,
"home_page": "",
"name": "foliantcontrib.dbmldoc",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Daniil Minukhin",
"author_email": "ddddsa@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fd/d6/9c1099bcf9a1f50df0f75af8de44f4c6eb623af34c8f9696322f04de94da/foliantcontrib.dbmldoc-0.3.4.tar.gz",
"platform": "any",
"description": "[](https://pypi.org/project/foliantcontrib.dbmldoc/) [](https://github.com/foliant-docs/foliantcontrib.dbmldoc)\n\n# DBML Docs Generator for Foliant\n\nThis preprocessor generates Markdown documentation from [DBML](https://www.dbml.org/) specification files . It uses [PyDBML](https://github.com/Vanderhoof/PyDBML) for parsing DBML syntax and [Jinja2](http://jinja.pocoo.org/) templating engine for generating Markdown.\n\n## Installation\n\n```bash\n$ pip install foliantcontrib.dbmldoc\n```\n\n## Config\n\nTo enable the preprocessor, add `dbmldoc` to `preprocessors` section in the project config:\n\n```yaml\npreprocessors:\n - dbmldoc\n```\n\nThe preprocessor has a number of options:\n\n```yaml\npreprocessors:\n - dbmldoc:\n spec_url: http://localhost/scheme.dbml\n spec_path: scheme.dbml\n doc: true\n scheme: true\n template: dbml.j2\n scheme_template: scheme.j2\n\n```\n\n`spec_url`\n: URL to DBML spec file. If it is a list \u2014 preprocessor uses the first url which works.\n\n`spec_path`\n: Local path to DBML spec file (relative to project dir).\n\n> If both url and path params are specified \u2014 preprocessor first tries to fetch spec from url, and only if that fails looks for the file on the local path.\n\n`doc`\n: If `true` \u2014 documentation will be generated. Set to `false` if you only want to draw a scheme of the database. Default `true`\n\n`scheme`\n: If `true` \u2014 the platuml code for database scheme will be generated. Default `true`\n\n`template`\n: Path to jinja-template for rendering the generated documentation. Path is relative to the project directory. If no template is specified preprocessor will use default template (and put it into project dir if it was missing). Default: `dbml.j2`\n\n> Note that the default template may be outdated. Please check if everything works, and if needed \u2014 update the template.\n\n`scheme_template`\n: Path to jinja-template for generating planuml code for the database scheme. Path is relative to the project directory. If no template is specified preprocessor will use default template (and put it into project dir if it was missing). Default: `scheme.j2`\n\n## Usage\n\nAdd a `<dbmldoc></dbmldoc>` tag at the position in the document where the generated documentation should be inserted:\n\n```html\n# Introduction\n\nThis document contains the automatically generated documentation of our Database schema.\n\n<dbmldoc></dbmldoc>\n```\n\nEach time the preprocessor encounters the tag `<dbmldoc></dbmldoc>` it inserts the whole generated documentation text instead of it. The path or url to DBML spec file is taken from foliant.yml.\n\nYou can also override some parameters (or all of them) in the tag options:\n\n```markdown\n# Introduction\n\nIntroduction text for API documentation.\n\n<dbmldoc spec_url=\"http://localhost/schema.dbml\"\n template=\"dbml.j2\"\n scheme=\"false\">\n</dbmldoc>\n\n# Database scheme\n\nAnd here goes a visual diagram of our database:\n\n<dbmldoc doc=\"false\" scheme=\"true\">\n</dbmldoc>\n```\n\n> Note that template path in tag is stated **relative to the markdown file**.\n\nTag parameters have the highest priority.\n\nThis way you can put your database description in one place and its diagram in the other (like in the example above). Or you can even have documentation from several different DBML spec files in one Foliant project.\n\n## Customizing output\n\nThe output markdown is generated by the [Jinja2](http://jinja.pocoo.org/) template. Inside the template all data from the parsed DBML file is available under the `data` variable. It is in fact a `PyDBMLParseResults` object, as returned by [PyDBML](https://github.com/Vanderhoof/PyDBML) (see the docs to find out which attributes are available).\n\nTo customize the output create a template which suits your needs. Then supply the path to it in the `template` parameter. Same goes for the scheme template, which is defined in the `scheme_template` parameter.\n\nIf you wish to use the default template as a starting point, build the foliant project with `dbmldoc` preprocessor turned on. After the first build the default templates will appear in your foliant project dir under the names `dbml.j2` and `scheme.j2`.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Documentation generator for DBML specification format",
"version": "0.3.4",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a61d3645c4c07a1cf04f1c74db996c31d797f8a4b73342eb00ecd5c8c7a2a15f",
"md5": "37ad41a5f391fcded68c6d3c17b5085a",
"sha256": "c2583764b115dbeed2a6ff2cca77f99f65cba64d13e571571396b461b0607f82"
},
"downloads": -1,
"filename": "foliantcontrib.dbmldoc-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "37ad41a5f391fcded68c6d3c17b5085a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7712,
"upload_time": "2023-06-15T17:27:49",
"upload_time_iso_8601": "2023-06-15T17:27:49.928024Z",
"url": "https://files.pythonhosted.org/packages/a6/1d/3645c4c07a1cf04f1c74db996c31d797f8a4b73342eb00ecd5c8c7a2a15f/foliantcontrib.dbmldoc-0.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fdd69c1099bcf9a1f50df0f75af8de44f4c6eb623af34c8f9696322f04de94da",
"md5": "c19de3457cecd8b517092af6cc89f6ab",
"sha256": "1d09701edb6d8c21e073f1d7ac7346c0b602e41468d39fe5996708a3b472f038"
},
"downloads": -1,
"filename": "foliantcontrib.dbmldoc-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "c19de3457cecd8b517092af6cc89f6ab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7096,
"upload_time": "2023-06-15T17:27:52",
"upload_time_iso_8601": "2023-06-15T17:27:52.068535Z",
"url": "https://files.pythonhosted.org/packages/fd/d6/9c1099bcf9a1f50df0f75af8de44f4c6eb623af34c8f9696322f04de94da/foliantcontrib.dbmldoc-0.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-15 17:27:52",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "foliantcontrib.dbmldoc"
}
