ibm-apidocs-cli 0.4.3

CLI library to automate the API Reference generation

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