From 20069313372192ea2af3b6e312246d6ef22c53a4 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Mon, 2 Sep 2024 13:46:47 +0900 Subject: [PATCH] Add getting started guide to README This is a first pass. As noted in the TODO, we should expand on this further but that's a job for another day. Change-Id: Icd44f0665995be66eba9f292e5c030be2ced9ac4 Signed-off-by: Stephen Finucane --- README.rst | 101 ++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 89 insertions(+), 12 deletions(-) diff --git a/README.rst b/README.rst index 28ba9dd..f9852cf 100644 --- a/README.rst +++ b/README.rst @@ -5,23 +5,100 @@ OpenStack CodeGenerator Primary goal of the project is to simplify maintainers life by generating complete or at least parts of the code. -OpenApi Schema -============== - CodeGenerator is able to generate OpenAPI specs for certain services by -inspecting their code. This requires service package being installed in the -environment where the generator is running. It then tries to initialize service -application and for supported runtimes scans for the exposed operations. At the -moment following services are covered: +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: - Nova - - Neutron - - Cinder - - Glance - - Keystone - - Octavia + +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.