{"id":15685844,"url":"https://github.com/amochin/robotframework-libtoc","last_synced_at":"2025-04-28T16:04:09.669Z","repository":{"id":62592113,"uuid":"499496782","full_name":"amochin/robotframework-libtoc","owner":"amochin","description":"Generates docs for an entire folder with Robot Framework resources/libs and creates a TOC for them","archived":false,"fork":false,"pushed_at":"2024-06-25T07:55:26.000Z","size":145,"stargazers_count":11,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-28T16:02:02.513Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amochin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-03T12:06:53.000Z","updated_at":"2025-04-11T11:53:11.000Z","dependencies_parsed_at":"2024-10-03T17:32:03.052Z","dependency_job_id":"f010f9d2-d920-4f4c-bc64-2a78ecb3a441","html_url":"https://github.com/amochin/robotframework-libtoc","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amochin%2Frobotframework-libtoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amochin%2Frobotframework-libtoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amochin%2Frobotframework-libtoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amochin%2Frobotframework-libtoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amochin","download_url":"https://codeload.github.com/amochin/robotframework-libtoc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251342721,"owners_count":21574244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T17:31:55.286Z","updated_at":"2025-04-28T16:04:09.293Z","avatar_url":"https://github.com/amochin.png","language":"Python","funding_links":[],"categories":["Tools"],"sub_categories":["Reporting Tools"],"readme":"## Robot Framework LibTOC\n\n## What it does\nThis 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\n\n## Why use it\nThe Robot Framework Libdoc tool normally generates a HTML file for a single keyword library or a resource file.\nIf you have several keyword libraries or resources, you just get several separate HTML files.\n\nThis tool collects separate keyword documentation files in one place and creates a TOC (table of contents) page\nwith links to these files.   \nThe result is a folder with several static HTML pages which can be placed somewhere \nin the intranet or uploaded as CI artifact - so everybody can easily access the keywords docs.\n\n### Here is the example screenshot\n![](Screenshot.png)\n\n## How it works\n- The tool goes through the specified folders with RF resources and it's **direct** subfolders\n- It looks for the **config files** named `.libtoc` which contain items you would like to create docs for:\n    1. Paths to resource/lib files in [glob format](https://en.wikipedia.org/wiki/Glob_(programming))\n    2. RF libraries, installed or available in PYTHONPATH using the provided fully qualified name\n        \u003e Librariy import params (if necessary) like described in [libdoc user guide](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#general-usage)\n        \u003e Other libdoc CLI options (e.g. version or name of the output file) are not supported\n    3. Paths to resource/lib files in [glob format](https://en.wikipedia.org/wiki/Glob_(programming)) inside Python packages, loaded from the PYTHONPATH\n        \u003e 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)\n    \n- 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\n- Finally it generates a **TOC (Table of Contents)** HTML page with links to all the generated HTML files.\n The navigation tree structure in the TOC repeats the folder tree structure.\n## Example of a `.libtoc` config file\n```\n[paths]\n# Use glob patterns\nsome-resources/**/*.robot\nsome-resources/**/*.resource\nsome-resources/**/*.py\n\n[libs]\n# Use RF library names with params - like for libdoc\nSeleniumLibrary\nRemote::http://10.0.0.42:8270\n# Import a library from PYTHONPATH using fully qualified name\nsome-libs.mylib.mypy\n# You can use environment variables in lib params\nSomeLib::$some_env_var/somepath\n\n[packages]\n# Use package name in python path and glob patterns separated by :\nsome-package:resources/**/*.resource\nsome-package:libs/**/*.py\n```\n\u003e The config file must contain at least one of the sections - `[paths]`, `[libs]`, `[packages]`\n## How to install it\n### System requirements\n- Python \u003e=3.7\n- Robot Framework\n### Installation using pip\n```shell\npip install robotframework-libtoc\n```\n\n## How to use it\n- Create the `.libtoc` config files in the *root of the resources folder* and/or in *direct subfolders* where you need docs to be created.    \n- Run `libtoc`. The last `resources_dirs` parameter is mandatory, it takes any number of paths. Other params are optional:\n    - `-d, --output_dir`\n    - `--config_file`\n    - `--toc_file`\n    - `--toc_template`\n    - `--homepage_template`\n    - `-P, --pythonpath`\n\n    Examples:\n    ```shell\n    libtoc example_resources\n    libtoc 'example_resources/SUT X' 'example_resources/SUT Y'\n    libtoc --output_dir docs example_resources\n    libtoc --output_dir docs --toc_file MY_SPECIAL_NAME_FOR_DOCS.html example_resources\n    libtoc --toc_template MY_CUSTOM_TOC.html --homepage_template MY_CUSTOM_HOMEPAGE.html example_resources\n    ```\n\n- Open the created file, e.g. `docs/keyword_docs.html`\n\n## How to change the TOC and the homepage HTML templates\nThe default HTML template files are located in the python installation directory (usually something like `\u003cpython_dir\u003e/lib/site-packages/robotframework_libtoc`) and can be changed if necessary.   \nIt's also possible to provide custom HTML template files using the `--toc_template` and `--homepage_template` options.\n\n## How to set the Python Path\nThere are two ways to extend the list of paths where the libraries are searched for:\n1. Using the `--pythonpath` option\n2. Set the **PYTHONPATH** environment variable\n\nSee more in [Robot Framework User Guide](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#pythonpath).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famochin%2Frobotframework-libtoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famochin%2Frobotframework-libtoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famochin%2Frobotframework-libtoc/lists"}