Files
303001e15e524ab34947e03fe4f2fd90d6523adf
codegenerator /README.rst

120 lines
4.0 KiB
ReStructuredText
Raw Normal View History

=======================
OpenStack CodeGenerator
=======================
Primary goal of the project is to simplify maintainers life by generating
complete or at least parts of the code.
CodeGenerator is able to generate OpenAPI specs for certain services by
inspecting their code and API Reference (api-ref) documentation. This requires
the service package be installed in the environment where the generator is
running. The generator then tries to initialize the service application and for
supported services scans for the exposed operations. At the moment the
following services are covered:
- Cinder
- Designate
- Glance
- Ironic
- Keystone
- Magnum
- Manila
- Neutron
- Nova
- Octavia
- Placement
In addition to building OpenAPI specs `CodeGenerator` is also used to build
SDK, CLI and TUI in Rust for OpenStack. Those live currently in `this GitHub
repository <https://github.com/gtema/openstack>`_.
.. note::
CodeGenerator is not intended to be used outside of OpenStack context (while
maybe it will even work). It is used primarily in the automatic pipelines.
For this reason it is not published to the PyPy.
Getting started
---------------
CodeGenerator is not currently packaged on PyPI (and may never be). As a
result, you must install from Git. For example:
.. code-block:: shell
$ git clone https://opendev.org/openstack/codegenerator
$ cd codegenerator
$ virtualenv .venv
$ source .venv/bin/activate
$ pip install -e .
Once installed, you can use the ``openstack-codegenerator`` for all operations.
The ``openstack-codegenerator`` provides a number of *targets*. These
correspond to the various steps required to get a functioning OpenAPI schema.
The first target is the ``openapi-spec`` target. This will generate an initial
OpenAPI schema through inspection of the chosen projects code and api-ref
documentation.
Let's generate an OpenAPI schema for the Compute service, Nova. To do this, we
first need to install Nova in the same virtualenv that we have installed
CodeGenerator in. Let's pull the Nova repo down locally and install it:
.. code-block:: shell
$ cd ..
$ git clone https://opendev.org/openstack/nova
$ cd -
$ pip install \
-c https://releases.openstack.org/constraints/upper/master
-r ../nova/requirements.txt
$ pip install -e ../nova
With Nova installed, we can now run ``openstack-codegenerator``:
.. code-block:: shell
$ openstack-codegenerator \
--work-dir wrk --target openapi-spec --service-type compute \
--validate
If you look in the path indicated by the ``--work-dir`` argument, you will find
a OpenAPI schema! However, this schema is rather incomplete. That's because
we inspected the Nova code but not the api-ref docs. To do that, we need to
pass a path to our docs, which means we need to build the docs locally. Let's
do this:
.. code-block:: shell
$ cd ../nova
$ tox -e api-ref
.. note::
The ``api-ref`` target *should* be consistent across projects. However,
it's not currently part of the `Project Testing Interface`__ so this isn't
guaranteed. If you find this target doesn't exist, look at your project's
``tox.ini`` file for clues.
.. __: https://governance.openstack.org/tc/reference/project-testing-interface.html
You should now have the documentation built in HTML format and available in the
``api-ref/build/html`` directory. Let's change back to the ``codegenerator``
directory and run ``openstack-codegenerator`` again, this time with an
additional ``--api-ref-src`` argument:
.. code-block:: shell
$ cde ../code-generator
$ openstack-codegenerator \
--work-dir wrk --target openapi-spec --service-type compute \
--api-ref-src ../nova/api-ref/build/html/index.html
--validate
Your API documentation should now be looking much better. You'll even have
documentation available inline.
There are a variety of options available, which you can view with the
``--help`` option.
.. todo: Expand on other targets, options.