Needs versioned Zanata API documentation
Description
Environment
Activity
Sean Flanigan 31 March 2017 at 02:44
Markdown's ability to embed HTML is actually quite limited (and often disabled for security), because it has very particular equirements. From memory, a blank line can turn off HTML mode, and I think only certain HTML tags can be used to switch from markdown to HTML mode. We wouldn't have bothered converting Zanata's Seam Text to Markdown if HTML inside Markdown had been a practical option.
I doubt readthedocs could handle the need for nested directories either.
Former user 31 March 2017 at 00:46
It would be nice if we can add API doc to readthedocs. That way everything is in a single place and versioned. It looks possible from https://github.com/mkdocs/mkdocs/issues/987 Some post processing may be required to do that.
Sean Flanigan 30 March 2017 at 02:26
I don't think readthedocs would work for publishing Enunciate's HTML docs (which are just part of a Maven site). The best free option would probably be GitHub Pages, eg https://github.github.com/maven-plugins/site-plugin/ But I don't know of any tools which support versioned deployments for Maven sites.
Former user 30 March 2017 at 02:04
Thanks for the feedback. Right now we only serve the latest in https://zanata.ci.cloudbees.com/job/zanata-api-site/site/zanata-common-api/rest-api-docs/index.html
We might looking at options to version it and host it in readthedocs.
Details
Details
Assignee
Reporter
Tested Version/s
Priority
unspecified
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