rmldoc
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.