Difference between revisions of "StarlingX/Developer Guide/API Documentation"
(→StarlingX API Brand New) |
(→StarlingX API Brand New) |
||
Line 44: | Line 44: | ||
Greg Waines did some research on this. | Greg Waines did some research on this. | ||
+ | |||
+ | <source lang="sh"> | ||
+ | [user@0756d97288e1 starlingx]$ repo grep mvn.repo.tgz | ||
+ | cgcs-root/stx/stx-integ/restapi-doc/centos/build_srpm.data: $CGCS_BASE/downloads/mvn.repo.tgz \ | ||
+ | cgcs-root/stx/stx-integ/restapi-doc/centos/restapi-doc.spec:Source1: mvn.repo.tgz | ||
+ | cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/Makefile: if [ ! -e mvn.repo.tgz ]; then \ | ||
+ | cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/Makefile: tar -xvzf ./mvn.repo.tgz -C ./mvn.repo/ | ||
+ | cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/Makefile.cache: cd mvn.repo && tar -czvf ../mvn.repo.tgz . && cd .. | ||
+ | cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/README.mvn_cache:Steps to produce mvn.repo.tgz [Maven cache] | ||
+ | cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/README.mvn_cache:mock -r $MY_BUILD_CFG_STD --copyout /builddir/build/BUILD/restapi-doc-1.6.0/mvn.repo.tgz ~/ | ||
+ | cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/README.mvn_cache:cp ~/mvn.repo.tgz $MY_REPO/stx/downloads/ | ||
+ | cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/README.mvn_cache:# ln -s ../../../downloads/mvn.repo.tgz mvn.repo.tgz | ||
+ | stx-tools/centos-mirror-tools/tarball-dl.lst:!mvn.repo.tgz#mvn#https://repo.maven.apache.org/maven2 | ||
+ | stx-tools/centos-mirror-tools/tarball-dl.sh: # The mvn.repo.tgz tarball will be created downloading a serie of | ||
+ | stx-tools/centos-mirror-tools/tarball-dl.sh: elif [ "$tarball_name" = "mvn.repo.tgz" ]; then | ||
+ | [user@0756d97288e1 starlingx]$ | ||
+ | </source> | ||
=== StarlingX API Existing === | === StarlingX API Existing === |
Revision as of 20:00, 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
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:
- NFVI Orchestration
- High Availability/Process Monitoring/Service Management
- StarlingX System Configuration Management
- Horizon plugins for new StarlingX services
- Installation/Update/Patching/Backup/Restore
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.
Starling API SysInv
(You may know this already) The StarlingX APIs (especially for sysinv) are currently documented at: https://git.openstack.org/cgit/openstack/stx-integ/tree/restapi-doc/restapi-doc You can use the content as a starting point. However, the mechanism used is outdated using maven and wadl files. So you need to use the more current approach.
Greg Waines did some research on this.
[user@0756d97288e1 starlingx]$ repo grep mvn.repo.tgz
cgcs-root/stx/stx-integ/restapi-doc/centos/build_srpm.data: $CGCS_BASE/downloads/mvn.repo.tgz \
cgcs-root/stx/stx-integ/restapi-doc/centos/restapi-doc.spec:Source1: mvn.repo.tgz
cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/Makefile: if [ ! -e mvn.repo.tgz ]; then \
cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/Makefile: tar -xvzf ./mvn.repo.tgz -C ./mvn.repo/
cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/Makefile.cache: cd mvn.repo && tar -czvf ../mvn.repo.tgz . && cd ..
cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/README.mvn_cache:Steps to produce mvn.repo.tgz [Maven cache]
cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/README.mvn_cache:mock -r $MY_BUILD_CFG_STD --copyout /builddir/build/BUILD/restapi-doc-1.6.0/mvn.repo.tgz ~/
cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/README.mvn_cache:cp ~/mvn.repo.tgz $MY_REPO/stx/downloads/
cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/README.mvn_cache:# ln -s ../../../downloads/mvn.repo.tgz mvn.repo.tgz
stx-tools/centos-mirror-tools/tarball-dl.lst:!mvn.repo.tgz#mvn#https://repo.maven.apache.org/maven2
stx-tools/centos-mirror-tools/tarball-dl.sh: # The mvn.repo.tgz tarball will be created downloading a serie of
stx-tools/centos-mirror-tools/tarball-dl.sh: elif [ "$tarball_name" = "mvn.repo.tgz" ]; then
[user@0756d97288e1 starlingx]$
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
- https://git.openstack.org/cgit/openstack/nova/tree/api-guide/source/index.rst
- https://developer.openstack.org/api-guide/compute/
API Ref
- https://git.openstack.org/cgit/openstack/nova/tree/api-ref/source/index.rst
- https://developer.openstack.org/api-ref/compute/
Specs
- http://git.openstack.org/cgit/openstack/nova-specs/
- https://specs.openstack.org/openstack/nova-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