[Starlingx-discuss] StarlingX API Documentation

[Arce Moreno, Abraham]

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 at 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/tarball-dl.sh
[1] http://lists.starlingx.io/pipermail/starlingx-discuss/2018-August/000530.html
[2] https://wiki.openstack.org/wiki/Documentation/APISite/DocumentingWadls
[3] https://wiki.openstack.org/wiki/StarlingX/Developer_Guide/API_Documentation