| Name | gddoc2yml JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | Convert godot xml docs to docfx yml |
| upload_time | 2024-05-16 06:41:53 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.6 |
| license | None |
| keywords |
godot
docfx
yml
xml
documentation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
# Godot Doc 2 Yml
Convert godot xml docs exported via the `godot --doctool` for gdscript
to yml compatible with docfx.
## Install
Install gddoc2yml via pip
```bash
python3 -m pip install gddoc2yml
```
Then you will have the gdxml2yml and gdxml2xrefmap command available:
<!-- markdownlint-disable MD013 -->
```bash
gdxml2yml -h
usage: gdxml2yml [-h] [--filter FILTER] path [path ...] output
Convert godot documentation xml file to yml for docfx.
positional arguments:
path A path to an XML file or a directory containing XML files to parse.
output output folder to store all generated yml files.
options:
-h, --help show this help message and exit
--filter FILTER The filepath pattern for XML files to filter
gdxml2xrefmap -h
usage: gdxml2xrefmap [-h] [--filter FILTER] path [path ...] output
Convert godot documentation xml files into a xrefmap compatible with DoxFx.
positional arguments:
path A path to an XML file or a directory containing XML files to parse.
output output path to store xrefmap.
options:
-h, --help show this help message and exit
--filter FILTER The filepath pattern for XML files to filter.
```
<!-- markdownlint-enable MD013 -->
## Using gddoc2yml
Export xml docs for your project with godot, us gdxml2yml to generate yml api,
then use the gd
1. Generate xml docs for your project.
Install godot command line tool (see
[Godot's Command Line Tutorial](https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html#path)
for details).
Export docs for your gdscript to xml via the `--doctool` flag.
```bash
# Example command to generate docs from scripts in project/scripts to dir doc/my-classes
godot --path project --doctool doc/my-classes --gdscript-docs res://scripts
```
2. Use gdxml2yml to generate yml docs for your project.
See references section for details on yml schema.
```bash
# You will also need the original xml docs from
# the godot repo, generate via godot --doctool <path>
# to generate godot docs at a given path
# $ mkdir ref
# $ godot --doctool ref
# Generate yml api for docfx.
# Generates output at folder out/my-classes/api
# Use the '--filter' flag to only generate docs for your files
gdxml2yml --filter doc/my-classes doc/my-classes ref out/my-classes/api
```
3. Use your generated yml in docfx. see the [doc/docfx.json](doc/docfx.json) for
an example. Make sure to include your api folder in the doc content
```json
{
"files": ["*.yml"],
"src": "api",
"dest": "api"
},
```
### Generating xrefmap for Godot Docs
Included is an additional command, `gdxml2xrefmap` to generate
an xrefmap for the godot docs.
```bash
gdxml2xrefmap godot/doc/classes godot/modules out/godot_xrefmap.yml
```
**Note** the build for this repo contains an xrefmap that points to godot's
documentation. You can reference this in your `docfx.json` file as a `xref`
like so:
```json
{
"build": {
"xref": [
"https://gddoc2yml.nickmaltbie.com/xrefmap/godot_xrefmap.yml"
]
}
}
```
## References
* [Godot -- CLI Reference](https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html#command-line-reference)
* [Godot -- make_rst.py](https://github.com/godotengine/godot/blob/master/doc/tools/make_rst.py)
* [DocFx -- Github](https://github.com/dotnet/docfx)
* [DocFx -- Introduction to Multiple Languages Support](https://xxred.gitee.io/docfx/tutorial/universalreference/intro_multiple_langs_support.html)
* [DocFx -- Custom Template](https://dotnet.github.io/docfx/docs/template.html?tabs=modern#custom-template)
* [DocFx -- .NET API Docs YAML Format](https://github.com/dotnet/docfx/blob/fe0bd0bfcbfecb655cc1cda2185df601fac1df23/docs/docs/dotnet-yaml-format.md)
* [DocFx -- PageViewModel.cs](https://github.com/dotnet/docfx/blob/main/src/Docfx.DataContracts.UniversalReference/PageViewModel.cs)
* [DocFx -- ItemViewModel.cs](https://github.com/dotnet/docfx/blob/main/src/Docfx.DataContracts.UniversalReference/ItemViewModel.cs)
* [DocFx -- Recommended XML tags for C#](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags)
## Development
This section consists of how to build and test the gddoc2yml project.
### Setup
Build package
```bash
# Install dependencies
python3 -m pip install -r requirements.txt
# Install build if required
# python3 -m pip install build
# Project will be created in dir dist
python3 -m build
```
### Linting
Lint using [flake8](https://github.com/pycqa/flake8/) tool.
```bash
# Run flake8 from .flake8 config file
# Install via python3 -m pip install flake8
python3 -m flake8 .
```
#### Markdown Linting
Markdown linting via [markdownlint](https://github.com/DavidAnson/markdownlint)
can be installed via npm.
```PowerShell
# Install cli version via npm
npm install -g markdownlint-cli
# Run on local repo
markdownlint .
```
### Tests
Run tests for project via Python's unittest module -- [Unit testing framework](https://docs.python.org/3/library/unittest.html)
```bash
python3 -m unittest
```
#### Code Coverage
Compute code coverage using [coveragepy](https://github.com/nedbat/coveragepy)
```bash
# Get code coverage using coverage
# Install via python -m pip install coverage
coverage run -m unittest discover
# Get results
coverage report -m
```
### Build and Use Latest Version
Build godot docs using latest gddoc2yml.
```bash
# Install from repo
python3 -m pip install .
# Generate docs using gdxml2yml
gdxml2yml godot/doc/classes godot/modules godot/platform/android/doc_classes doc/godot/api
# Generate xrefmap using gdxml2xrefmap
gdxml2xrefmap godot/doc/classes godot/modules doc/xrefmap/godot_xrefmap.yml
# Startup docfx website
dotnet tool run docfx --serve doc/docfx.json
```
Raw data
{
"_id": null,
"home_page": null,
"name": "gddoc2yml",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "godot, docfx, yml, xml, documentation",
"author": null,
"author_email": "Nick Maltbie <nick.dmalt@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/87/ab/9ef7bd039bc9ca01a6d698df2e2f2e7167372280501b12a52d77c53c1b02/gddoc2yml-0.2.0.tar.gz",
"platform": null,
"description": "# Godot Doc 2 Yml\n\nConvert godot xml docs exported via the `godot --doctool` for gdscript\nto yml compatible with docfx.\n\n## Install\n\nInstall gddoc2yml via pip\n\n```bash\npython3 -m pip install gddoc2yml\n```\n\nThen you will have the gdxml2yml and gdxml2xrefmap command available:\n\n<!-- markdownlint-disable MD013 -->\n\n```bash\ngdxml2yml -h\n usage: gdxml2yml [-h] [--filter FILTER] path [path ...] output\n\n Convert godot documentation xml file to yml for docfx.\n\n positional arguments:\n path A path to an XML file or a directory containing XML files to parse.\n output output folder to store all generated yml files.\n\n options:\n -h, --help show this help message and exit\n --filter FILTER The filepath pattern for XML files to filter\n\ngdxml2xrefmap -h\n usage: gdxml2xrefmap [-h] [--filter FILTER] path [path ...] output\n\n Convert godot documentation xml files into a xrefmap compatible with DoxFx.\n\n positional arguments:\n path A path to an XML file or a directory containing XML files to parse.\n output output path to store xrefmap.\n\n options:\n -h, --help show this help message and exit\n --filter FILTER The filepath pattern for XML files to filter.\n```\n\n<!-- markdownlint-enable MD013 -->\n\n## Using gddoc2yml\n\nExport xml docs for your project with godot, us gdxml2yml to generate yml api,\nthen use the gd\n\n1. Generate xml docs for your project.\n\n Install godot command line tool (see\n [Godot's Command Line Tutorial](https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html#path)\n for details).\n\n Export docs for your gdscript to xml via the `--doctool` flag.\n\n ```bash\n # Example command to generate docs from scripts in project/scripts to dir doc/my-classes\n godot --path project --doctool doc/my-classes --gdscript-docs res://scripts\n ```\n\n2. Use gdxml2yml to generate yml docs for your project.\n See references section for details on yml schema.\n\n ```bash\n # You will also need the original xml docs from\n # the godot repo, generate via godot --doctool <path>\n # to generate godot docs at a given path\n # $ mkdir ref\n # $ godot --doctool ref\n\n # Generate yml api for docfx.\n # Generates output at folder out/my-classes/api\n # Use the '--filter' flag to only generate docs for your files\n gdxml2yml --filter doc/my-classes doc/my-classes ref out/my-classes/api\n ```\n\n3. Use your generated yml in docfx. see the [doc/docfx.json](doc/docfx.json) for\n an example. Make sure to include your api folder in the doc content\n\n ```json\n {\n \"files\": [\"*.yml\"],\n \"src\": \"api\",\n \"dest\": \"api\"\n },\n ```\n\n### Generating xrefmap for Godot Docs\n\nIncluded is an additional command, `gdxml2xrefmap` to generate\nan xrefmap for the godot docs.\n\n```bash\ngdxml2xrefmap godot/doc/classes godot/modules out/godot_xrefmap.yml\n```\n\n**Note** the build for this repo contains an xrefmap that points to godot's\ndocumentation. You can reference this in your `docfx.json` file as a `xref`\nlike so:\n\n```json\n{\n \"build\": {\n \"xref\": [\n \"https://gddoc2yml.nickmaltbie.com/xrefmap/godot_xrefmap.yml\"\n ]\n }\n}\n```\n\n## References\n\n* [Godot -- CLI Reference](https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html#command-line-reference)\n* [Godot -- make_rst.py](https://github.com/godotengine/godot/blob/master/doc/tools/make_rst.py)\n* [DocFx -- Github](https://github.com/dotnet/docfx)\n* [DocFx -- Introduction to Multiple Languages Support](https://xxred.gitee.io/docfx/tutorial/universalreference/intro_multiple_langs_support.html)\n* [DocFx -- Custom Template](https://dotnet.github.io/docfx/docs/template.html?tabs=modern#custom-template)\n* [DocFx -- .NET API Docs YAML Format](https://github.com/dotnet/docfx/blob/fe0bd0bfcbfecb655cc1cda2185df601fac1df23/docs/docs/dotnet-yaml-format.md)\n* [DocFx -- PageViewModel.cs](https://github.com/dotnet/docfx/blob/main/src/Docfx.DataContracts.UniversalReference/PageViewModel.cs)\n* [DocFx -- ItemViewModel.cs](https://github.com/dotnet/docfx/blob/main/src/Docfx.DataContracts.UniversalReference/ItemViewModel.cs)\n* [DocFx -- Recommended XML tags for C#](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags)\n\n## Development\n\nThis section consists of how to build and test the gddoc2yml project.\n\n### Setup\n\nBuild package\n\n```bash\n# Install dependencies\npython3 -m pip install -r requirements.txt\n\n# Install build if required\n# python3 -m pip install build\n# Project will be created in dir dist\npython3 -m build\n```\n\n### Linting\n\nLint using [flake8](https://github.com/pycqa/flake8/) tool.\n\n```bash\n# Run flake8 from .flake8 config file\n# Install via python3 -m pip install flake8\npython3 -m flake8 .\n```\n\n#### Markdown Linting\n\nMarkdown linting via [markdownlint](https://github.com/DavidAnson/markdownlint)\ncan be installed via npm.\n\n```PowerShell\n# Install cli version via npm\nnpm install -g markdownlint-cli\n\n# Run on local repo\nmarkdownlint .\n```\n\n### Tests\n\nRun tests for project via Python's unittest module -- [Unit testing framework](https://docs.python.org/3/library/unittest.html)\n\n```bash\npython3 -m unittest\n```\n\n#### Code Coverage\n\nCompute code coverage using [coveragepy](https://github.com/nedbat/coveragepy)\n\n```bash\n# Get code coverage using coverage\n# Install via python -m pip install coverage\ncoverage run -m unittest discover\n\n# Get results\ncoverage report -m\n```\n\n### Build and Use Latest Version\n\nBuild godot docs using latest gddoc2yml.\n\n```bash\n# Install from repo\npython3 -m pip install .\n\n# Generate docs using gdxml2yml\ngdxml2yml godot/doc/classes godot/modules godot/platform/android/doc_classes doc/godot/api\n\n# Generate xrefmap using gdxml2xrefmap\ngdxml2xrefmap godot/doc/classes godot/modules doc/xrefmap/godot_xrefmap.yml\n\n# Startup docfx website\ndotnet tool run docfx --serve doc/docfx.json\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Convert godot xml docs to docfx yml",
"version": "0.2.0",
"project_urls": {
"Changelog": "https://github.com/nicholas-maltbie/gddoc2yml/blob/main/CHANGELOG.md",
"GitHub": "https://github.com/nicholas-maltbie/gddoc2yml",
"Homepage": "https://github.com/nicholas-maltbie/gddoc2yml",
"Issues": "https://github.com/nicholas-maltbie/gddoc2yml/issues"
},
"split_keywords": [
"godot",
" docfx",
" yml",
" xml",
" documentation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "79cd5be555a13b06a3200ab1ad0168f1875cd6442456c826b9ff23cf463e6a05",
"md5": "87fe5c93ba6e2c999eaa08cdf2853559",
"sha256": "fe20c1e713a60d842cb5c0ea34a25a7452dea1028585d57581db87fd0710cb9e"
},
"downloads": -1,
"filename": "gddoc2yml-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "87fe5c93ba6e2c999eaa08cdf2853559",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 43083,
"upload_time": "2024-05-16T06:41:51",
"upload_time_iso_8601": "2024-05-16T06:41:51.454604Z",
"url": "https://files.pythonhosted.org/packages/79/cd/5be555a13b06a3200ab1ad0168f1875cd6442456c826b9ff23cf463e6a05/gddoc2yml-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "87ab9ef7bd039bc9ca01a6d698df2e2f2e7167372280501b12a52d77c53c1b02",
"md5": "ef68f86620c4d960af3c8a58fc277448",
"sha256": "9c93dc8ccd8625d6e183cdf1401ef57a2c3d3f0da7c7dd5c836270a4a00ee6b2"
},
"downloads": -1,
"filename": "gddoc2yml-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "ef68f86620c4d960af3c8a58fc277448",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 81161,
"upload_time": "2024-05-16T06:41:53",
"upload_time_iso_8601": "2024-05-16T06:41:53.851649Z",
"url": "https://files.pythonhosted.org/packages/87/ab/9ef7bd039bc9ca01a6d698df2e2f2e7167372280501b12a52d77c53c1b02/gddoc2yml-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-16 06:41:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nicholas-maltbie",
"github_project": "gddoc2yml",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"lcname": "gddoc2yml"
}
