# RF Documentations Indexer
Rfdocsindexer is a simple Python3 module to generate [RobotFramework](https://robotframework.org/) 4+ libraries documentation.
One can configure the tool from a simple [TOML](https://github.com/toml-lang/toml) configuration file and run it from a console.
The tool then uses the RobotFramework [Libdoc](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#libdoc) module to generate an HTML, XML, JSON or Libspec documentation for any RobotFramework keyword library.
An HTML index is also generated to centralize the generated documentations.
Below is an overview of the HTML index generated. It makes it easy to navigate among external resources and keywords documentation.
## Installing the tool
Install from Pypi:
```bash
pip install rfdocsindexer
```
## Configuring the tool
The tool can be configured with a config file in [TOML](https://github.com/toml-lang/toml) format.
Example configuration file:
```toml
[rfdocsindexer]
library_paths = ["**/libraries/*.robot", "my_library.resource"]
library_names = ["MyLibrary", "MyOtherLibary.MyOtherLibrary"]
extra_modules_searchpaths = ["./library_dir"]
external_resources = ["RF homepage | https://robotframework.org/", "http://example.org"]
build_machine_readable_libdoc = true
include_robotframework_resources = true
```
The configuration file must contain the section `[rfdocindexer]` and any or none of the following options:
* `library_paths`: a list of paths (glob format accepted) to RF resource files (can be `*.resource`, `*.robot`, `*.spec`...)
* `library_names`: a list of RF library modules
* `extra_modules_searchpaths`: a list of paths to append to `PYTHONPATH`
* `external_resources`: a list of URLs which will be added to the HTML index file, or `<name> | <URL>`. Useful to include frequently used external resources when developing tests.
* `build_machine_readable_libdoc`: whether to generate documentation in XML, JSON and Libspec format. If set to `False`, only the HTML documenation will be generated. Default is `False`.
* `include_robotframework_resources`: whether to generate documentation for default RobotFramework libraries (`BuiltIn`, `Collection`, ...). Default is `True`.
## Running the tool
In a standard shell, run the following:
```bash
# To generate documentation for default RobotFramework libraries
indexrfdocs
# To specify the configuration file to use
indexrfdocs -c path/to/configfile.toml
# To specify the output directory (content will not be erased if already existing), default is "rfdocs"
indexrfdocs -o path/to/outdir
```
Raw data
{
"_id": null,
"home_page": "https://github.com/Vincema/rfdocsindexer",
"name": "rfdocsindexer",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "RobotFramework, Documentation, Libdocs, Testing",
"author": "Vincent Maire",
"author_email": "maire.vincent31@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a4/2a/e064c86ee2f059601e0cc19ae6bbfb3d24b8ec91997a87cd21ec3d658ce1/rfdocsindexer-1.3.0.tar.gz",
"platform": null,
"description": "# RF Documentations Indexer\n\nRfdocsindexer is a simple Python3 module to generate [RobotFramework](https://robotframework.org/) 4+ libraries documentation.\n\nOne can configure the tool from a simple [TOML](https://github.com/toml-lang/toml) configuration file and run it from a console.\n\nThe tool then uses the RobotFramework [Libdoc](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#libdoc) module to generate an HTML, XML, JSON or Libspec documentation for any RobotFramework keyword library.\n\nAn HTML index is also generated to centralize the generated documentations.\n\n\n\nBelow is an overview of the HTML index generated. It makes it easy to navigate among external resources and keywords documentation.\n\n\n\n## Installing the tool\n\nInstall from Pypi:\n```bash\npip install rfdocsindexer\n```\n\n## Configuring the tool\n\nThe tool can be configured with a config file in [TOML](https://github.com/toml-lang/toml) format.\n\nExample configuration file:\n\n```toml\n[rfdocsindexer]\nlibrary_paths = [\"**/libraries/*.robot\", \"my_library.resource\"]\nlibrary_names = [\"MyLibrary\", \"MyOtherLibary.MyOtherLibrary\"]\nextra_modules_searchpaths = [\"./library_dir\"]\nexternal_resources = [\"RF homepage | https://robotframework.org/\", \"http://example.org\"]\nbuild_machine_readable_libdoc = true\ninclude_robotframework_resources = true\n```\n\nThe configuration file must contain the section `[rfdocindexer]` and any or none of the following options:\n\n* `library_paths`: a list of paths (glob format accepted) to RF resource files (can be `*.resource`, `*.robot`, `*.spec`...)\n* `library_names`: a list of RF library modules\n* `extra_modules_searchpaths`: a list of paths to append to `PYTHONPATH`\n* `external_resources`: a list of URLs which will be added to the HTML index file, or `<name> | <URL>`. Useful to include frequently used external resources when developing tests.\n* `build_machine_readable_libdoc`: whether to generate documentation in XML, JSON and Libspec format. If set to `False`, only the HTML documenation will be generated. Default is `False`.\n* `include_robotframework_resources`: whether to generate documentation for default RobotFramework libraries (`BuiltIn`, `Collection`, ...). Default is `True`.\n\n\n## Running the tool\n\nIn a standard shell, run the following:\n\n```bash\n# To generate documentation for default RobotFramework libraries\nindexrfdocs\n\n# To specify the configuration file to use\nindexrfdocs -c path/to/configfile.toml\n\n# To specify the output directory (content will not be erased if already existing), default is \"rfdocs\"\nindexrfdocs -o path/to/outdir\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A simple and configurable generator for RobotFramework documentation",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://github.com/Vincema/rfdocsindexer",
"Repository": "https://github.com/Vincema/rfdocsindexer"
},
"split_keywords": [
"robotframework",
" documentation",
" libdocs",
" testing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4027b3fb8f32fd03fbc2dca15c0b68d79d3a5cb026814b4b021da140ea42c803",
"md5": "1851b39b966ab79452d1f12041ac5e32",
"sha256": "b0458b72f455dd5537accc0d955e2634ec1fcce09474ba2300ef9edb5e2ad45e"
},
"downloads": -1,
"filename": "rfdocsindexer-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1851b39b966ab79452d1f12041ac5e32",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 14091,
"upload_time": "2024-07-29T13:44:58",
"upload_time_iso_8601": "2024-07-29T13:44:58.150749Z",
"url": "https://files.pythonhosted.org/packages/40/27/b3fb8f32fd03fbc2dca15c0b68d79d3a5cb026814b4b021da140ea42c803/rfdocsindexer-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a42ae064c86ee2f059601e0cc19ae6bbfb3d24b8ec91997a87cd21ec3d658ce1",
"md5": "22b62dcf9fad221b393f11d5a9229708",
"sha256": "8bc8fecb49a63550d88a94ec945588ad323efc99eec2829b962ca053677bf149"
},
"downloads": -1,
"filename": "rfdocsindexer-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "22b62dcf9fad221b393f11d5a9229708",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 13002,
"upload_time": "2024-07-29T13:44:59",
"upload_time_iso_8601": "2024-07-29T13:44:59.154228Z",
"url": "https://files.pythonhosted.org/packages/a4/2a/e064c86ee2f059601e0cc19ae6bbfb3d24b8ec91997a87cd21ec3d658ce1/rfdocsindexer-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-29 13:44:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Vincema",
"github_project": "rfdocsindexer",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "rfdocsindexer"
}
JSON
