Difference between revisions of "StarlingX/Developer Guide/API Documentation"

Revision as of 16:47, 7 August 2018

Intro

StarlingX team is working in collaboration with Tech Writing team to document StarlingX APIs, this page reflects the research on what it means for StarlingX.

History

Starlingx-discuss: StarlingX API Documentation

OpenStack API

For this activity we are initially be considering from API Documentation 2 separate efforts for each project:

API Guide .. the concepts in the API
API Ref .. a reference for the API

Both concepts (API Guide) and the ref (API Ref) need to be be written at the same time. The new OpenStack approach allows for tags to go in the code.

StarlingX API

We categorize the StarlingX APIs in 2:

Brand New APIs from StarlingX projects
Existing APIs from OpenStack projects

StarlingX should not document other OpenStack API's.

StarlingX API Brand New

The projects falling into this category are the following:

All projects in the Flock should be included. I think there is a dependency on some of the code restructuring activities that are underway, we need to make sure these activities don't collide.

StarlingX API Existing

We have not gone through a deeper review if we are modifying/adding new calls into the OpenStack projects however if we are and we need to document them:

There is official OpenStack <Project> API documentation, we can make references to them for the existing calls
What about the modifications/additions? Should we document them? What is the best place for this? We were talking in our weekly call about stx-docs is a good place for things without a repo, is this a good example?
Any easy way besides "find + grep" to get where those API modifications are happening?

StarlingX API Unit Tests

OpenStack projects includes Unit Tests. To be considered if this is required.

OpenStack Learning Corner

Nova Project

This is a good project to work with since it has the 2 projects related to APIs, the Guide and Ref, I have also included Specs to see if that applies.

API Guide

API Ref

Specs

Zuul

Search for Nova
https://git.openstack.org/cgit/openstack-infra/project-config/tree/zuul.d/projects.yaml

Zuul (continuous integration, delivery, and deployment) allows us to enable that automatic publishing based on templates:

- project:
    name: openstack/nova
    templates:
      - openstack-python-jobs
      - openstack-python35-jobs
      - periodic-jobs-with-oslo-master
      - publish-openstack-sphinx-docs
      - release-openstack-server
      - periodic-stable-jobs
      - check-requirements
      - integrated-gate
      - integrated-gate-py35
      - translation-jobs
      - translation-jobs-queens
      - translation-jobs-rocky
      - release-notes-jobs
      - api-guide-jobs
      - api-ref-jobs

Masakari

@@ Line 6: / Line 6: @@
 * [http://lists.starlingx.io/pipermail/starlingx-discuss/2018-August/000516.html Starlingx-discuss: StarlingX API Documentation]
+== OpenStack API ==
+For this activity we are initially be considering from API Documentation 2 separate efforts for each project:
+* API Guide .. the concepts in the API
+* API Ref .. a reference for the API
+<br>
+Both concepts (API Guide) and the ref (API Ref) need to be be written at the same time.  The new OpenStack approach allows for tags to go in the code.
 == StarlingX API ==
@@ Line 40: / Line 49: @@
 OpenStack projects includes Unit Tests. To be considered if this is required.
-== OpenStack API ==
+== OpenStack Learning Corner ==
-For this activity we are initially be considering from API Documentation 2 separate efforts for each project:
-* API Guide .. the concepts in the API
-* API Ref .. a reference for the API
-<br>
-Both concepts (API Guide) and the ref (API Ref) need to be be written at the same time.  The new OpenStack approach allows for tags to go in the code.
 === Nova Project ===