RAML API Docs Generator for Foliant
This preprocessor generates Markdown documentation from RAML spec files. It uses raml2html converter with raml2html-full-markdown-theme.
raml2html uses Nunjucks templating system.
Installation
First install raml2html and the markdown theme:
$ npm install -g raml2html raml2html-full-markdown-theme
Then install the preprocessor:
$ pip install foliantcontrib.ramldoc
Config
To enable the preprocessor, add ramldoc to preprocessors section in the project config:
preprocessors:
- ramldoc
The preprocessor has a number of options:
preprocessors:
- ramldoc:
spec_url: http://localhost/my_api.raml
spec_path: !path my_api.raml
template_dir: !path custom_templates
raml2html_path: raml2html
spec_url
: URL to RAML spec file. If it is a list — preprocessor picks the first working URL.
spec_path
: Local path to RAML spec file.
If both URL and path are specified — preprocessor first tries to fetch spec from URL, and then (if that fails) looks for the file on local path.
template_dir
: Path to directory with Nunjucks templates. If not specified — default template is used. The main template in the directory must have a name root.nunjucks.
raml2html_path
: Path to raml2html binary. Default: raml2html
Usage
Add a <ramldoc></ramldoc> tag at the position in the document where the generated documentation should be inserted:
# Introduction
This document contains the automatically generated documentation of our API.
<ramldoc></ramldoc>
Each time the preprocessor encounters the tag <ramldoc></ramldoc> it inserts the whole generated documentation text instead of it. The path or url to RAML spec file are taken from foliant.yml.
You can also specify some parameters (or all of them) in the tag options:
# Introduction
Introduction text for API documentation.
<ramldoc spec_url="http://localhost/my_api.raml"
template_dir="assets/templates">
</ramldoc>
Tag parameters have the highest priority.
This way you can have documentation from several different RAML spec files in one Foliant project (even in one md-file if you like it so).
Customizing output
The output markdown is generated by raml2html converter, which uses Nunjucks templating engine (with syntax similar to Jinja2. If you want to create your own template or modify the default one, specify the template_dir parameter.
The main template file in template dir must be named root.nunjucks.
You may use the default template as your starting point.
Metadata
Release files for foliantcontrib.ramldoc 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| foliantcontrib.ramldoc-1.0.2.tar.gz | 5.2 kB | Without provenance | Details for foliantcontrib.ramldoc-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| foliantcontrib.ramldoc-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for foliantcontrib.ramldoc-1.0.2-py3-none-any.whl |
Total release size: 10.5 kB
Release files / foliantcontrib.ramldoc-1.0.2.tar.gz
| Download URL | foliantcontrib.ramldoc-1.0.2.tar.gz |
|---|---|
| Size | 5.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8d95be68efb44d4a3bf8ceb3baf7bd319f0f964de36e4214fc92b053c8852387
|
|
BLAKE2b-256 checksum How to use checksums |
8279a1d48a1a68340725d21625c179e0419abb043cc214ae263016ee2b951fbb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.4.1 importlib_metadata/4.6.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.61.0 CPython/3.9.5
|
Release files / foliantcontrib.ramldoc-1.0.2-py3-none-any.whl
| Download URL | foliantcontrib.ramldoc-1.0.2-py3-none-any.whl |
|---|---|
| Size | 5.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
59e1b521cebb93d4fda17c821824020caaaaed6b4b6d75282c682554dcee0353
|
|
BLAKE2b-256 checksum How to use checksums |
eaaf89dec1710f9a944cafc78ec736d14ba5ecf8086d84863db11dd391d5f02b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.4.1 importlib_metadata/4.6.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.61.0 CPython/3.9.5
|
Security for foliantcontrib.ramldoc 1.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.