Skip to main content

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:

    1. Paths to resource/lib files in glob format
    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 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 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 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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

robotframework_libtoc-1.4.2.tar.gz (13.1 kB view details)

Uploaded Source

Built Distribution

robotframework_libtoc-1.4.2-py3-none-any.whl (13.3 kB view details)

Uploaded Python 3

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

Hashes for robotframework_libtoc-1.4.2.tar.gz
Algorithm Hash digest
SHA256 5f49dee9a72d1248f2fc8b8359e75b611541295c42df94f0d97efceb44ba7867
MD5 15fa22684394e4c3f89fd081b6dae0cc
BLAKE2b-256 abd50b71aae738c945c3a90f5efa67cc3f50666db5ce0c31b4b86dde909309e5

See more details on using hashes here.

File details

Details for the file robotframework_libtoc-1.4.2-py3-none-any.whl.

File metadata

File hashes

Hashes for robotframework_libtoc-1.4.2-py3-none-any.whl
Algorithm Hash digest
SHA256 95e2e9731658e97d8e8c3e2afa6605d5305f0cdd91345f28d841fdac671aa3f5
MD5 92f11810b409b628754b41ad5941d134
BLAKE2b-256 419d7e8e3f9ba5c660a65079a5ec577df10736b7bfbcc552a4475145bf209307

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page