RMLdoc

RMLdoc is a tool designed to simplify the process of generating documentation of mappings used for knowledge graph construction. It automates the documentation generation process, allowing users to easily understand the mapping transformation rules defined within their projects. Given an input mapping file written in R2RML, RML, or YARRRML, RMLdoc will generate a detailed Markdown documentation explaining each mapping with corresponding diagrams, in a human readable manner.

Features

• Automated Documentation Generation: RMLdoc automatically generates documentation for mappings, eliminating the need for manual documentation efforts.
• Clear and Readable Output: The generated documentation provides clear and concise descriptions of the input data sources, subject and predicate-object descriptions, along with other components defined within the mappings and their metadata.
• Command-Line Interface (CLI): RMLdoc provides a simple command-line interface for easy integration into existing workflows and build processes.

Installation

From pypi

RMLdoc is available in pypi!

pip install rmldoc

From source

To install RMLdoc, simply clone this repository and cd in the main folder. Then install the package:

pip install -e .

Usage

rmldoc offers the following options:

usage: rmldoc [-h] -i INPUT_MAPPING_PATH [-o OUTPUT_PATH]

optional arguments:
  -h, --help            show this help message and exit
  
  -i INPUT_MAPPING_PATH, --input_mapping_path INPUT_MAPPING_PATH
                        Path to the input mapping file in RML format.
  -o OUTPUT_PATH, --output_path OUTPUT_PATH
                        Path to save the generated document. Default output in output.md
  -y, --yatter          Enable yatter option to read yarrrml mappings

To generate documentation for your mappings, use the following command, where you would replace path/to/rml/mappings.rml with the path to your RML mapping file and path/to/output/directory/mappings.md with the file where you want the documentation to be generated:

rmldoc -i path/to/rml/mappings.rml - o path/to/output/directory/mappings.md

To automate documentation generation using GNU's make, a typical implementation would involve creating a makefile with the following structure:

doc-rml:  ## Generate documentation for RML
	@echo -e "\033[35m > Generate documentation for RML \033[0m - requires RMLdoc: see https://github.com/oeg-upm/rmldoc"
	@find mapping/ -type f -name *.ttl \
		-printf "\n%f\n" \
		-exec rmldoc -i {} -o {}.md \;
	@echo -e "\033[35m > Done  \033[0m"

Example

The following link shows the result produced by RMLdoc from the following mapping file.

RMLdoc specification

The RMLdoc specification describes the main metadata expected in a RML mapping file. Have a look to create eye-catching documentations!

Contributing

Contributions to RMLdoc are welcome! If you encounter any issues or have suggestions for improvements, please open an issue or submit a pull request on GitHub.

Authors

• Jhon Toledo (ja.toledo@upm.es)
• Ana Iglesias-Molina
• David Chaves-Fraga
• Daniel Garijo