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 must be accessible to enable generating the front-matter Markdown file. The repository should be cloned or downloaded to the machine where the `ibm-apidocs-cli` command will be run. The required `--frontmatter` argument specifies the full path to the `app.js` file.
Install the SDK generator
The OpenAPI SDK Code Generator must be accessible to enable generating the language-specific files. 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](https://github.ibm.com/CloudEngineering/openapi-sdkgen/releases) to install the generator on the machine where the `ibm-apidocs-cli` command will be run. For more information, see [the generator README](https://github.ibm.com/CloudEngineering/openapi-sdkgen#using-a-pre-built-installer). The required `--sdk-generator` argument specifies the full path to the `openapi-sdkgen.jar` file. **Note:** The SDK generator .jar file must be named `openapi-sdkgen.jar`. If you have downloaded or built a version of the file with a different name (e.g. `openapi-sdkgen-<version>.jar`), you must rename it.
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> -c <config_file> -f <frontmatter_path> -s <sdk_generator_path> [-a <apidocs_path>] [--templates <templates_path>] [--output_folder <output_path>] [--keep_sdk] [--verbose] [--version] Generate the apidocs files. Required arguments: -i <openapi_file>, --openapi <openapi_file> The path to the input OpenAPI specification (e.g. `assistant-v1.json`). -c <config_file>, --config <config_file> The 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. -f <frontmatter_path>, --frontmatter <frontmatter_path> Path to the directory containing the front-matter generator `app.js` file. -s <sdk_generator_path>, --sdk_generator <sdk_generator_path> Path to the directory containing the SDK generator `openapi-sdkgen.jar` file. optional arguments: --apidocs <apidocs_path> The path to the `cloud-api-docs` repository or other directory containing `apiref-index.json` and front matter config file. If you do not specify this argument, the current directory is used. --templates <templates_path> Path to a directory containing custom front-matter templates. --output_folder <output_folder> The target directory for generated files. If you do not specify this argument, output files are written to the current directory. --keep_sdk Preserve the `_sdktemp` directory containing generated SDK artifacts. Useful for debugging purposes. --no_update Use front-matter config file as-is without updating SDK versions. If you do not specify this argument, the config file is updated with the latest GitHub release for each supported SDK language. -h, --help Show this help message and exit. --verbose Verbose flag. --version Show program's version number and exit.
Example commands
This example assumes that the command is being run from the apidocs repo directory containing the API Reference files. All output files are written to the current directory:
ibm-apidocs-cli -i assistant-v1.json -c assistant-v1-config.json\
-f '/Users/my_user/GitHub/frontmatter-generator' \
-s '/Users/my_user/openapi-sdkgen/lib'
This example uses different locations for the input and output files:
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.4.4.tar.gz
(8.9 kB
view hashes)