Metadata-Version: 2.1
Name: rfdocsindexer
Version: 0.1.2
Summary: A simple and configurable generator for RobotFramework documentation
Home-page: https://github.com/Vincema/rfdocsindexer
License: Apache-2.0
Keywords: RobotFramework,Documentation,Libdocs,Testing
Author: Vincent Maire
Author-email: maire.vincent31@gmail.com
Requires-Python: >=3.7,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Robot Framework
Classifier: Framework :: Robot Framework :: Tool
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Unix
Classifier: Operating System :: iOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Dist: Jinja2 (>=3.0.1,<4.0.0)
Requires-Dist: click (>=8.0.1,<9.0.0)
Requires-Dist: pydantic (>=1.8.2,<2.0.0)
Requires-Dist: robotframework (>=4,<5)
Requires-Dist: toml (>=0.10.2,<0.11.0)
Project-URL: Repository, https://github.com/Vincema/rfdocsindexer
Description-Content-Type: text/markdown

# RF Documentations Indexer

Rfdocsindexer is a simple Python3 module to generate [RobotFramework](https://robotframework.org/) 4+ libraries documentation.

One can configure the tool from a simple [TOML](https://github.com/toml-lang/toml) configuration file and run it from a console.

The tool then uses the RobotFramework [Libdoc](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#libdoc) module to generate an HTML, XML, JSON or Libspec documentation for any RobotFramework keyword library.

An HTML index is also generated to centralize the generated documentations.

![RFDocsIndexer Diagram](https://github.com/Vincema/rfdocsindexer/blob/main/docs/diagrams/rfdocsindexer_diagram.svg)

## Installing the tool

Install from Pypi:
```bash
pip install rfdocsindexer
```

## Configuring the tool

The tool can be configured with a config file in [TOML](https://github.com/toml-lang/toml) format.

Example configuration file:

```toml
[rfdocsindexer]
library_paths = ["**/libraries/*.robot", "my_library.resource"]
library_names = ["MyLibrary", "MyOtherLibary.MyOtherLibrary"]
extra_modules_searchpaths = ["./library_dir"]
external_resources = ["RF homepage | https://robotframework.org/", "http://example.org"]
build_machine_readable_libdoc = true
include_robotframework_resources = true
```

The configuration file must contain the section `[rfdocindexer]` and any or none of the following options:

* `library_paths`: a list of paths (glob format accepted) to RF resource files (can be `*.resource`, `*.robot`, `*.spec`...)
* `library_names`: a list of RF library modules
* `extra_modules_searchpaths`: a list of paths to append to `PYTHONPATH`
* `external_resources`: a list of URLs which will be added to the HTML index file, or `<name> | <URL>`. Useful to include frequently used external resources when developing tests.
* `build_machine_readable_libdoc`: whether to generate documentation in XML, JSON and Libspec format. If set to `False`, only the HTML documenation will be generated. Default is `False`.
* `include_robotframework_resources`: whether to generate documentation for default RobotFramework libraries (`BuiltIn`, `Collection`, ...). Default is `True`.


## Running the tool

In a standard shell, run the following:

```bash
# To generate documentation for default RobotFramework libraries
indexrfdocs

# To specify the configuration file to use
indexrfdocs -c path/to/configfile.toml

# To specify the output directory (content will not be erased if already existing), default is "rfdocs"
indexrfdocs -o path/to/outdir
```

