https://github.com/amochin/robotframework-libtoc
Generates docs for an entire folder with Robot Framework resources/libs and creates a TOC for them
https://github.com/amochin/robotframework-libtoc
Last synced: over 1 year ago
JSON representation
Generates docs for an entire folder with Robot Framework resources/libs and creates a TOC for them
- Host: GitHub
- URL: https://github.com/amochin/robotframework-libtoc
- Owner: amochin
- License: apache-2.0
- Created: 2022-06-03T12:06:53.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-06-25T07:55:26.000Z (about 2 years ago)
- Last Synced: 2025-04-28T16:02:02.513Z (over 1 year ago)
- Language: Python
- Homepage:
- Size: 142 KB
- Stars: 11
- Watchers: 2
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-robotframework - LibToc - This tool generates docs using Robot Framework Libdoc for an entire folder (or multiple folders) with Robot Framework resources/libs and creates a TOC (table of contents) file for them. (Tools / Reporting Tools)
README
## Robot Framework LibTOC
## What it does
This tool generates docs using Robot Framework [Libdoc](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#libdoc) for an entire folder (or multiple folders) with Robot Framework resources/libs and creates a TOC (table of contents) file for them
## Why use it
The Robot Framework Libdoc tool normally generates a HTML file for a single keyword library or a resource file.
If you have several keyword libraries or resources, you just get several separate HTML files.
This tool collects separate keyword documentation files in one place and creates a TOC (table of contents) page
with links to these files.
The result is a folder with several static HTML pages which can be placed somewhere
in the intranet or uploaded as CI artifact - so everybody can easily access the keywords docs.
### Here is the example screenshot
## How it works
- The tool goes through the specified folders with RF resources and it's **direct** subfolders
- It looks for the **config files** named `.libtoc` which contain items you would like to create docs for:
1. Paths to resource/lib files in [glob format](https://en.wikipedia.org/wiki/Glob_(programming))
2. RF libraries, installed or available in PYTHONPATH using the provided fully qualified name
> Librariy import params (if necessary) like described in [libdoc user guide](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#general-usage)
> Other libdoc CLI options (e.g. version or name of the output file) are not supported
3. Paths to resource/lib files in [glob format](https://en.wikipedia.org/wiki/Glob_(programming)) inside Python packages, loaded from the PYTHONPATH
> See more about bundling RF resources in Python packages in [RF User Guide](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#taking-resource-files-into-use)
- Then it generates the docs using `libdoc` - both for files paths, resolved from the glob patterns, and for the installed libraries. The created HTML files are placed in the **libtoc output_dir** - keeping the original subfolder structure of resources
- Finally it generates a **TOC (Table of Contents)** HTML page with links to all the generated HTML files.
The navigation tree structure in the TOC repeats the folder tree structure.
## Example of a `.libtoc` config file
```
[paths]
# Use glob patterns
some-resources/**/*.robot
some-resources/**/*.resource
some-resources/**/*.py
[libs]
# Use RF library names with params - like for libdoc
SeleniumLibrary
Remote::http://10.0.0.42:8270
# Import a library from PYTHONPATH using fully qualified name
some-libs.mylib.mypy
# You can use environment variables in lib params
SomeLib::$some_env_var/somepath
[packages]
# Use package name in python path and glob patterns separated by :
some-package:resources/**/*.resource
some-package:libs/**/*.py
```
> The config file must contain at least one of the sections - `[paths]`, `[libs]`, `[packages]`
## How to install it
### System requirements
- Python >=3.7
- Robot Framework
### Installation using pip
```shell
pip install robotframework-libtoc
```
## How to use it
- Create the `.libtoc` config files in the *root of the resources folder* and/or in *direct subfolders* where you need docs to be created.
- Run `libtoc`. The last `resources_dirs` parameter is mandatory, it takes any number of paths. Other params are optional:
- `-d, --output_dir`
- `--config_file`
- `--toc_file`
- `--toc_template`
- `--homepage_template`
- `-P, --pythonpath`
Examples:
```shell
libtoc example_resources
libtoc 'example_resources/SUT X' 'example_resources/SUT Y'
libtoc --output_dir docs example_resources
libtoc --output_dir docs --toc_file MY_SPECIAL_NAME_FOR_DOCS.html example_resources
libtoc --toc_template MY_CUSTOM_TOC.html --homepage_template MY_CUSTOM_HOMEPAGE.html example_resources
```
- Open the created file, e.g. `docs/keyword_docs.html`
## How to change the TOC and the homepage HTML templates
The default HTML template files are located in the python installation directory (usually something like `/lib/site-packages/robotframework_libtoc`) and can be changed if necessary.
It's also possible to provide custom HTML template files using the `--toc_template` and `--homepage_template` options.
## How to set the Python Path
There are two ways to extend the list of paths where the libraries are searched for:
1. Using the `--pythonpath` option
2. Set the **PYTHONPATH** environment variable
See more in [Robot Framework User Guide](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#pythonpath).