CLI library to automate the API Reference generation
Project description
This tool allows users to generate the api documentation.
Installation
To install, use pip or easy_install:
pip install -U ibm-apidocs-cli
or
easy_install -U ibm-apidocs-cli
Install the Frontmatter generator
The front-matter generator repository should be accessible to enable the call to app.js. The repository should be cloned or downloaded to the machine where the ibm-apidocs-cli command will be run. The command uses an argument "--frontmatter" where you will need to specify the full path to the apps.js file.
Install the SDK generator
The OpenAPI SDK Code Generator should be accessible to enable the call to openapi-sdkgen.jar. You do not need to clone or download the full repository and build the project. It is much easier to use the pre-built installer under releases and install it on the machine where the ibm-apidocs-cli command will be run. The command uses an argument "--sdk-generator" where you will need to specify the full path to the openapi-sdkgen.jar file. Instructions for installing the pre-built installer are in the openapi-sdkgen README.md file under the section Using a pre-built installer.
Clone or create a cloud-api-docs repo
The build process requires access to the directory containing the `apiref-index.json` file and the front matter configuration file (typically `<openapi>-config.json`) for the cloud-api-docs repo used to publish the API documentation.
Usage
ibm-apidocs-cli --help
usage: ibm-apidocs-cli [-h] -i <openapi_file> -a <apidocs_path> -c <config_file> [--frontmatter <frontmatter_path>] [--sdk-generator <sdk_generator_path>] [--output_folder <output_path>] [--verbose] [--version] Generate the apidocs files. Required arguments: -i <openapi_file>, --openapi <openapi_file> The input OpenAPI specification file path or url. -a <apidocs_path>, --apidocs <apidocs_path> The path to the cloud-api-docs repository or other directory containing `apiref-index.json` and front matter config file. -c <config_file>, --config <config_file> File name of front matter config file (e.g. `assistant-v1-config.json`). You can optionally specify the full path to the config file; if you do not include the path, the file is assumed to be in the `apidocs` directory. optional arguments: -h, --help show this help message and exit --frontmatter <frontmatter_path> Path to the directory containing the frontmatter generator `app.js` file. --sdk_generator <sdk_generator_path> Path to the directory containing the SDK generator JAR file. --output_folder output_folder The target directory for generated files. --verbose verbose flag --version show program's version number and exit
Example command: (At this time full pathnames are necessary to execute the command) All the generated apidocs and artifacts from the command will be written to the target output folder ibm-apidocs-cli --openapi '/Users/my_user/Documents/GitHub/api-apidocs-cli/test/resources/config/assistant-openapi3-v1.json' \ --config '/Users/my_user/Documents/GitHub/api-apidocs-cli/test/resources/config/test-input-config.yaml' \ --output_folder '/Users/my_user/Documents/GitHub/api-apidocs-cli/test/target' \ --frontmatter '/Users/my_user/Documents/GitHub/frontmatter-generator' \ --sdk_generator '/Users/my_user/Documents/Release/openapi-sdkgen/lib'
Python version
✅ Tested on Python 2.7, 3.4, 3.5, and 3.6.
Contributing
See CONTRIBUTING.md.
License
MIT
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
ibm-apidocs-cli-0.0.4.tar.gz
(8.3 kB
view hashes)
Built Distribution
Close
Hashes for ibm_apidocs_cli-0.0.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4c11f7581b7858bb70d125674d9f8bd0b0d3c53469ad61743b2a114a8dd00c78 |
|
MD5 | a9cd816875358181a43061635feacac8 |
|
BLAKE2b-256 | e8f7dc1c1e8bb2a412b12d5159d922ecd608beeca4cb6f62e8910d2cd883ad0f |