robotframework-libtoc 1.4.0

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, 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 files in glob format
  2. Paths to resources files in glob format inside packages loaded from the pythonpath
  3. Installed RF libraries - names and necessary import params like described in libdoc user guide

     Other libdoc CLI options (e.g. version or name of the output file) are not supported

• 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
**/*.robot
**/*.resource
**/*.py

[packages]
example_package:resources/**/*.resource

[libs]
# Use RF library names with params - like for libdoc
SeleniumLibrary
Remote::http://10.0.0.42:8270
# You can use environment variables in lib params
SomeLib::$some_env_var/somepath

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 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:

  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:

1. Using the --pythonpath option
2. Set the PYTHONPATH environment variable

See more in Robot Framework User Guide.