Needs versioned Zanata API documentation

Description

Hello,

OpenStack I18n team so well uses Zanata in https://translate.openstack.org/ with Zanata 3.9.6 currently. It works so well with kind support from Zanata development. I really appreciate all the things from the initiation of migration from Transifex to Zanata [1], Zanata production upgrade from 3.7.3 to 3.9.6 [2], listening to and dealing with many feedbacks on Zanata [3], and so on.

Now I wanna to ask for versioned Zanata API documentation [4].

In my opinion, now only API documentation but also well making use of API documentation with interesting use-cases will help better Internationalization. OpenStack I18n team tried to make use of Zanata APIs according to Zanata API documentation. One use case is to calculate the statistics for Zanata users (zanata_stats.py). The other use case is to retrieve name and e-mail addresses from Zanata user id (zanata_userinfo.py). Furthermore, the list of Zanata users are currently retrieved by crawling the list of language team and each language team pages [6] since current Zanata API user list implementation is for project-based (zanata_users.py). I hope that several more use-cases will be identified and reflected into openstack/i18n repository.

To more encourage Zanata API applications in openstack/i18n repository, now, I am considering to make a form of a Python package called i18n-zanata-tools like openstack-doc-tools [7]. It would be much nice if Zanata development team will involve it by reviewing good usage of Zanata APIs. Also, I hope that such approach will also benefit to more Zanata users who are in different world rather than OpenStack.

When I am considering such idea, I just have found that [4] is not versioned. I asked it to pahuang briefly on #zanata IRC channel, and he mentioned that "the api doc I think it's generated from master branch. so it's not versioned . it shouldn't be hard to host one for each version.". In my opinion, Zanata API documentation version will follow Zanata CLI versions [8]. It would be so great if Zanata team will provide versioned API documentations so OpenStack I18n team better keeps track of use-case development approach as I mentioned.

Note: my idea on "i18n-zanata-tools" is just draft and I need to discuss more with OpenStack I18n members but I think the direction seems so fine and I18n people will like my idea hopefully

With many thanks,

/Ian

[1] http://princessleia.com/journal/2015/09/the-migration-of-openstack-translations-to-zanata/
[2] https://blueprints.launchpad.net/openstack-i18n/+spec/ocata-zanata-upgrade
[3] https://etherpad.openstack.org/p/I18n-Zanata-enhancement
[4] https://zanata.ci.cloudbees.com/job/zanata-api-site/site/zanata-common-api/rest-api-docs/index.html
[5] http://git.openstack.org/cgit/openstack/i18n/tree/tools/zanata
[6] https://translate.openstack.org/language/list
[7] https://pypi.python.org/pypi/openstack-doc-tools
[8] https://raw.githubusercontent.com/zanata/zanata.github.io/master/files/0install/zanata-cli.xml

Environment

None

Status

Assignee

Unassigned

Reporter

Ian Y. Choi

Labels

None

Tested Version/s

None

External Issue Link

None

Imported Bugzilla Number

None

Priority

unspecified
Configure