Metadata-Version: 2.1
Name: ibm-apidocs-cli
Version: 0.4.3
Summary: CLI library to automate the API Reference generation
Home-page: https://cloud.ibm.com/apidocs
Author: IBM Corp
Author-email: germanatt@us.ibm.com
License: MIT
Keywords: api-reference,ibm-watson,ibm-cloud
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Dist: requests (<3.0,>=2.0)
Requires-Dist: outdated (>=0.2.0)
Requires-Dist: lxml (==4.3.1)
Requires-Dist: PyYAML (==3.13)

ibm-apidocs-cli
===============

|Status| |Latest Stable Version|

This tool allows users to generate the api documentation.

Installation
------------

To install, use ``pip`` or ``easy_install``:

.. code:: bash

   pip install -U ibm-apidocs-cli

or

.. code:: bash

   easy_install -U ibm-apidocs-cli

Install the `Frontmatter
generator <https://github.ibm.com/cloud-doc-build/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 <https://github.ibm.com/CloudEngineering/openapi-sdkgen/releases>`__

::

   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 <https://github.ibm.com/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:

.. code:: bash

   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 <./CONTRIBUTING.md>`__.

License
-------

MIT

.. |Status| image:: https://img.shields.io/badge/status-beta-yellow.svg
.. |Latest Stable Version| image:: https://img.shields.io/pypi/v/ibm-apidocs-cli.svg
   :target: https://pypi.python.org/pypi/ibm-apidocs-cli


