Docs and TOC generator for Robot Framework resources and libs
Project description
Robot Framework LibTOC
What it does
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
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:- Paths to resource/lib files in glob format
- RF libraries, installed or available in PYTHONPATH using the provided fully qualified name
Librariy import params (if necessary) like described in libdoc user guide Other libdoc CLI options (e.g. version or name of the output file) are not supported
- Paths to resource/lib files in glob format inside Python packages, loaded from the PYTHONPATH
See more about bundling RF resources in Python packages in RF User Guide
-
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
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 lastresources_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:
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 <python_dir>/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:
- Using the
--pythonpath
option - Set the PYTHONPATH environment variable
See more in Robot Framework User Guide.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file robotframework_libtoc-1.4.2.tar.gz
.
File metadata
- Download URL: robotframework_libtoc-1.4.2.tar.gz
- Upload date:
- Size: 13.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.8.3 CPython/3.12.4 Darwin/23.5.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5f49dee9a72d1248f2fc8b8359e75b611541295c42df94f0d97efceb44ba7867 |
|
MD5 | 15fa22684394e4c3f89fd081b6dae0cc |
|
BLAKE2b-256 | abd50b71aae738c945c3a90f5efa67cc3f50666db5ce0c31b4b86dde909309e5 |
File details
Details for the file robotframework_libtoc-1.4.2-py3-none-any.whl
.
File metadata
- Download URL: robotframework_libtoc-1.4.2-py3-none-any.whl
- Upload date:
- Size: 13.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.8.3 CPython/3.12.4 Darwin/23.5.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 95e2e9731658e97d8e8c3e2afa6605d5305f0cdd91345f28d841fdac671aa3f5 |
|
MD5 | 92f11810b409b628754b41ad5941d134 |
|
BLAKE2b-256 | 419d7e8e3f9ba5c660a65079a5ec577df10736b7bfbcc552a4475145bf209307 |