Re: [Starlingx-discuss] StarlingX API Documentation
Hi Abraham; Thanks for kicking this off. On 2018-08-03, 12:40 PM, "Arce Moreno, Abraham" <abraham.arce.moreno@intel.com> wrote: A new goal in collaboration with our Tech Writing team is to document StarlingX APIs, so we did an initial research on what it means for StarlingX so your feedback is highly appreciated. [ 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 Can we prioritize one over the other? We should do the concepts and the ref at the same time. The new OpenStack approach allows for tags to go in the code. Let's start with this work. [ StarlingX :: API ] It seems we can 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, would their documentation not the source of truth? [ StarlingX :: API :: Brand New ] The projects falling into this category are the following: - [0] NFVI Orchestration - [1] High Availability/Process Monitoring/Service Management - [2] StarlingX System Configuration Management - [3] Horizon plugins for new StarlingX services - [4] Installation/Update/Patching/Backup/Restore Can we considered all the above to be included in this API documentation effort? Are we missing any other? 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. Ian [ StarlingX :: API :: Existing ] All projects living under our starlingx-staging github organization [5] with upstream contributions [6] e.g. horizon, ceilometer, etc. 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. Is this something we also need to consider for our StarlingX Bran New APIs? [0] http://git.openstack.org/cgit/openstack/stx-nfv/ [1] http://git.openstack.org/cgit/openstack/stx-ha/ [2] http://git.openstack.org/cgit/openstack/stx-config/ [3] http://git.openstack.org/cgit/openstack/stx-gui/ [4] http://git.openstack.org/cgit/openstack/stx-update/ [5] https://github.com/starlingx-staging [6] http://git.openstack.org/cgit/openstack/stx-upstream/tree/openstack _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Hi Abraham, (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-... 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. I strongly recommend you review with him when he's back from vacation (Tues Aug 7). Is this the story you are working on: https://storyboard.openstack.org/#!/story/2002712 ? If so, I'll add some of the details Greg has captured to the story. Regards, Ghada -----Original Message----- From: Jolliffe, Ian [mailto:Ian.Jolliffe@windriver.com] Sent: Friday, August 03, 2018 3:38 PM To: Arce Moreno, Abraham; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] StarlingX API Documentation Hi Abraham; Thanks for kicking this off. On 2018-08-03, 12:40 PM, "Arce Moreno, Abraham" <abraham.arce.moreno@intel.com> wrote: A new goal in collaboration with our Tech Writing team is to document StarlingX APIs, so we did an initial research on what it means for StarlingX so your feedback is highly appreciated. [ 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 Can we prioritize one over the other? We should do the concepts and the ref at the same time. The new OpenStack approach allows for tags to go in the code. Let's start with this work. [ StarlingX :: API ] It seems we can 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, would their documentation not the source of truth? [ StarlingX :: API :: Brand New ] The projects falling into this category are the following: - [0] NFVI Orchestration - [1] High Availability/Process Monitoring/Service Management - [2] StarlingX System Configuration Management - [3] Horizon plugins for new StarlingX services - [4] Installation/Update/Patching/Backup/Restore Can we considered all the above to be included in this API documentation effort? Are we missing any other? 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. Ian [ StarlingX :: API :: Existing ] All projects living under our starlingx-staging github organization [5] with upstream contributions [6] e.g. horizon, ceilometer, etc. 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. Is this something we also need to consider for our StarlingX Bran New APIs? [0] http://git.openstack.org/cgit/openstack/stx-nfv/ [1] http://git.openstack.org/cgit/openstack/stx-ha/ [2] http://git.openstack.org/cgit/openstack/stx-config/ [3] http://git.openstack.org/cgit/openstack/stx-gui/ [4] http://git.openstack.org/cgit/openstack/stx-update/ [5] https://github.com/starlingx-staging [6] http://git.openstack.org/cgit/openstack/stx-upstream/tree/openstack _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Abraham, How are these built into documents? I was playing around with the instructions in the README.mvn_cache file from my Ubuntu box and can't seem to create a mvn.repo.tgz following those steps. Scott -----Original Message----- From: Khalil, Ghada [mailto:Ghada.Khalil@windriver.com] Sent: Friday, August 3, 2018 3:42 PM To: Jolliffe, Ian <Ian.Jolliffe@windriver.com>; Arce Moreno, Abraham <abraham.arce.moreno@intel.com>; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] StarlingX API Documentation Hi Abraham, (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-... 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. I strongly recommend you review with him when he's back from vacation (Tues Aug 7). Is this the story you are working on: https://storyboard.openstack.org/#!/story/2002712 ? If so, I'll add some of the details Greg has captured to the story. Regards, Ghada -----Original Message----- From: Jolliffe, Ian [mailto:Ian.Jolliffe@windriver.com] Sent: Friday, August 03, 2018 3:38 PM To: Arce Moreno, Abraham; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] StarlingX API Documentation Hi Abraham; Thanks for kicking this off. On 2018-08-03, 12:40 PM, "Arce Moreno, Abraham" <abraham.arce.moreno@intel.com> wrote: A new goal in collaboration with our Tech Writing team is to document StarlingX APIs, so we did an initial research on what it means for StarlingX so your feedback is highly appreciated. [ 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 Can we prioritize one over the other? We should do the concepts and the ref at the same time. The new OpenStack approach allows for tags to go in the code. Let's start with this work. [ StarlingX :: API ] It seems we can 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, would their documentation not the source of truth? [ StarlingX :: API :: Brand New ] The projects falling into this category are the following: - [0] NFVI Orchestration - [1] High Availability/Process Monitoring/Service Management - [2] StarlingX System Configuration Management - [3] Horizon plugins for new StarlingX services - [4] Installation/Update/Patching/Backup/Restore Can we considered all the above to be included in this API documentation effort? Are we missing any other? 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. Ian [ StarlingX :: API :: Existing ] All projects living under our starlingx-staging github organization [5] with upstream contributions [6] e.g. horizon, ceilometer, etc. 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. Is this something we also need to consider for our StarlingX Bran New APIs? [0] http://git.openstack.org/cgit/openstack/stx-nfv/ [1] http://git.openstack.org/cgit/openstack/stx-ha/ [2] http://git.openstack.org/cgit/openstack/stx-config/ [3] http://git.openstack.org/cgit/openstack/stx-gui/ [4] http://git.openstack.org/cgit/openstack/stx-update/ [5] https://github.com/starlingx-staging [6] http://git.openstack.org/cgit/openstack/stx-upstream/tree/openstack _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Hi Scott!
How are these built into documents? I was playing around with the instructions in the README.mvn_cache file from my Ubuntu box and can't seem to create a mvn.repo.tgz following those steps.
To create our StarlingX ISO there are 2 phases: - Build of the CentOS Mirror repository - Build of StarlingX Packages and ISO mvn.repo.tgz is created in the first phase, during the build of the CentOS Mirror repository, specifically in the download and packaging of the Tarball Compressed files [0] and then taken as an input of the Build Packages based on the Spec File: stx-integ/restapi-doc/centos/restapi-doc.spec We depend on a RPM based Linux distro for its generation, I am not sure how tightly coupled it is to our StarlingX Build System to take it out to build individually and based on the comments from Ghada [1] : " However, the mechanism used is outdated using maven and wadl files. So you need to use the more current approach. " So main effort might be to migrate from wadl to OpenStack Doc. I do not know if there is a way to translate but a specific OpenStack related documentation talks about this format [2] For now, I have created a StarlingX Wiki page to document all our StarlingX API journey [3] This is the output of where mvn.repo.tgz is reference across our StarlingX code. [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 [0] https://git.openstack.org/cgit/openstack/stx-tools/tree/centos-mirror-tools/... [1] http://lists.starlingx.io/pipermail/starlingx-discuss/2018-August/000530.htm... [2] https://wiki.openstack.org/wiki/Documentation/APISite/DocumentingWadls [3] https://wiki.openstack.org/wiki/StarlingX/Developer_Guide/API_Documentation
Thanks Ghada!
(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.
I was not aware of :) understood so we will take a look.
Greg Waines did some research on this. I strongly recommend you review with him when he's back from vacation (Tues Aug 7).
Ok
Is this the story you are working on: https://storyboard.openstack.org/#!/story/2002712 ? If so, I'll add some of the details Greg has captured to the story.
Yes, this is the story.
... yeah forgot to mention the point that Ghada makes below, we currently use a very very out-dated approach to API Documentation ... i.e. Grizzly timeframe ... which uses maven and wadl files ... very ugly. This approach also had the API documentation centralized in one spot ... whereas now the API documentation seems to live (correctly) in the same git as the code. So we additionally need to convert our API Documentation to the current format being used for OpenStack API Doc and should distribute the API documentation appropriately to the appropriate StarlingX sub-projects. Greg. From: "Khalil, Ghada" <Ghada.Khalil@windriver.com> Date: Friday, August 3, 2018 at 6:41 PM To: "Jolliffe, Ian" <Ian.Jolliffe@windriver.com>, "Arce Moreno, Abraham" <abraham.arce.moreno@intel.com>, "starlingx-discuss@lists.starlingx.io" <starlingx-discuss@lists.starlingx.io> Cc: Greg Waines <Greg.Waines@windriver.com> Subject: RE: [Starlingx-discuss] StarlingX API Documentation Hi Abraham, (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-... 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. I strongly recommend you review with him when he's back from vacation (Tues Aug 7). Is this the story you are working on: https://storyboard.openstack.org/#!/story/2002712 ? If so, I'll add some of the details Greg has captured to the story. Regards, Ghada -----Original Message----- From: Jolliffe, Ian [mailto:Ian.Jolliffe@windriver.com] Sent: Friday, August 03, 2018 3:38 PM To: Arce Moreno, Abraham; starlingx-discuss@lists.starlingx.io<mailto:starlingx-discuss@lists.starlingx.io> Subject: Re: [Starlingx-discuss] StarlingX API Documentation Hi Abraham; Thanks for kicking this off. On 2018-08-03, 12:40 PM, "Arce Moreno, Abraham" <abraham.arce.moreno@intel.com<mailto:abraham.arce.moreno@intel.com>> wrote: A new goal in collaboration with our Tech Writing team is to document StarlingX APIs, so we did an initial research on what it means for StarlingX so your feedback is highly appreciated. [ 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 Can we prioritize one over the other? We should do the concepts and the ref at the same time. The new OpenStack approach allows for tags to go in the code. Let's start with this work. [ StarlingX :: API ] It seems we can 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, would their documentation not the source of truth? [ StarlingX :: API :: Brand New ] The projects falling into this category are the following: - [0] NFVI Orchestration - [1] High Availability/Process Monitoring/Service Management - [2] StarlingX System Configuration Management - [3] Horizon plugins for new StarlingX services - [4] Installation/Update/Patching/Backup/Restore Can we considered all the above to be included in this API documentation effort? Are we missing any other? 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. Ian [ StarlingX :: API :: Existing ] All projects living under our starlingx-staging github organization [5] with upstream contributions [6] e.g. horizon, ceilometer, etc. 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. Is this something we also need to consider for our StarlingX Bran New APIs? [0] http://git.openstack.org/cgit/openstack/stx-nfv/ [1] http://git.openstack.org/cgit/openstack/stx-ha/ [2] http://git.openstack.org/cgit/openstack/stx-config/ [3] http://git.openstack.org/cgit/openstack/stx-gui/ [4] http://git.openstack.org/cgit/openstack/stx-update/ [5] https://github.com/starlingx-staging [6] http://git.openstack.org/cgit/openstack/stx-upstream/tree/openstack _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io<mailto:Starlingx-discuss@lists.starlingx.io> http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io<mailto:Starlingx-discuss@lists.starlingx.io> http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Thanks Ian!
[ OpenStack :: API ]
- API Guide .. the concepts in the API - API Ref .. a reference for the API Can we prioritize one over the other?
We should do the concepts and the ref at the same time. The new OpenStack approach allows for tags to go in the code. Let's start with this work.
Understood.
[ StarlingX :: API ]
It seems we can 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, would their documentation not the source of truth?
They are :) let's prioritize Flock.
[ StarlingX :: API :: Brand New ]
The projects falling into this category are the following:
- [0] NFVI Orchestration - [1] High Availability/Process Monitoring/Service Management - [2] StarlingX System Configuration Management - [3] Horizon plugins for new StarlingX services - [4] Installation/Update/Patching/Backup/Restore
Can we considered all the above to be included in this API documentation effort? Are we missing any other?
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.
Yep! As discussed in the thread [Starlingx-discuss] Restructuring round 2 [0] [0] http://lists.starlingx.io/pipermail/starlingx-discuss/2018-August/000499.htm...
participants (5)
-
Arce Moreno, Abraham
-
Jolliffe, Ian
-
Khalil, Ghada
-
Rifenbark, ScottX
-
Waines, Greg