19:01:28 #startmeeting docs 19:01:28 Meeting started Tue May 17 19:01:28 2016 UTC. The chair is colindixon. Information about MeetBot at http://ci.openstack.org/meetbot.html. 19:01:28 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 19:01:28 The meeting name has been set to 'docs' 19:01:47 #topic agenda bashing 19:02:14 colindixon: https://git.opendaylight.org/gerrit/#/c/38899/ 19:03:05 going to rebase brb 19:07:05 https://git.opendaylight.org/gerrit/#/c/38847/ 19:08:17 #link last time we covered what a migration to read the docs might look like: https://meetings.opendaylight.org/opendaylight-docs/2016/docs/opendaylight-docs-docs.2016-05-10-19.01.html 19:09:06 #link https://lists.opendaylight.org/pipermail/documentation/2016-May/000700.html colindixon asked how to integrate javadoc, REST API docs, etc. with read the docs 19:10:05 #info the answer seems to be we're not any worse than the last way, in both directions it accepts static HTML, so we ought to be able to do that 19:10:43 https://opendaylight.readthedocs.io/en/latest/ 19:11:56 #topic progress on read the docs 19:12:43 #link https://opendaylight.readthedocs.io/en/latest/ you can now see the infrastructure guide which has releng/builder docs even though they're hosted in the releng/builder repo 19:13:20 #info anipbu says we should talk about what terms to use, handbook vs. guide vs. manual 19:14:19 #info zxiiro notes that we only use handbook at the root of the new readthedocs page, colindixon notes that manual is only used in the file system structure 19:14:57 #info it appears as though we call everything a guide except that all the guides together are called the handbook 19:15:00 Handbook is a collection of Guides. 19:15:40 #topic introducing this work to the broader community 19:16:05 #info on the TSC call last week, some people seemed somewhat upset about moving away from asciidocs 19:16:10 https://git.opendaylight.org/gerrit/#/q/project:docs+status:open,25 19:17:39 #info we need to explain how and when this will happen and how it will be done to avoid people 19:17:54 #topic preparing for Boron docs reviews 19:19:50 #action colindixon to contacat a docs review committee including abhijitkumbhare, ChrisPriceAB, CaseyODL, dfarrell07, and anipbu are the first bit 19:21:28 #action anipbu to set up a documentation review spreadsheet 19:21:36 I will be tracking the Documentation Matrix for Boron here: https://docs.google.com/spreadsheets/d/1d-Qay-9IAy5OIECPGHj-Xtw24ey6UEzIEk9RSJuD5uo/edit#gid=22029863 19:21:37 #link https://docs.google.com/spreadsheets/d/1PYxjiSYEks44uJByVO1P44rnI5xTJRulpKyrSsDQF9g/edit?pli=1#gid=613128231 this is the one I used for Lithium 19:24:35 #link https://docs.google.com/spreadsheets/d/1d-Qay-9IAy5OIECPGHj-Xtw24ey6UEzIEk9RSJuD5uo/edit#gid=22029863 anipbu documentation tracking sheet 19:25:53 #topic back to bringing sphinx/readthedocs/rst to the community 19:27:33 #info colindixon notes that we need to do a TWS to introduce people to this toolchain at some point 19:27:40 #info zxiiro says getting projects to convert would be good before then 19:27:52 #info maybe getting the infrastructure folks to do that 19:30:26 #link colindixon asks about having a verify jobs for sphinx, we are getting close to having one for docs: https://git.opendaylight.org/gerrit/#/c/38951/ 19:31:52 #info after that, we either need to use that for all docs and trigger it on all project changes on docs in those projects when they build 19:32:38 #action colindixon to look at converting TTP docs to RST and sphinx, zxiiro offers to help anipbu with USC 19:34:09 #info anipbu asks about a guide for migration, zxiiro says there isn't one yet, and there isn't a patch that coverts a document in place 19:35:00 #info colindixon says it sounds a week from this Monday is probably as early as we could imagine having this in the shape that we want 19:36:05 #topic boron plans 19:38:24 #info anipbu asks if we want everyone to move all projects to read the docs in Boron, colindixon says he'd love to, but he doesn't see how we could do that in boron unless the docs team has to figure out hwo to move all projects 19:40:13 https://git.opendaylight.org/gerrit/gitweb?p=docs.git;a=tree;f=manuals/getting-started-guide/src/main/asciidoc/ovsdb; 19:42:24 #info colindixon says that in his mind, you probably want to completely convert or not convert things on a guide-by-guide basis 19:43:05 http://hyperpolyglot.org/lightweight-markup <-- Colin links in tool for conversion 19:45:09 #info e.g., we might convert the getting started guide and (maybe) the openstack guide 19:46:11 #action colindixon to work with projects in the getting started guide to migrate to RST and be in the new getting started guide 19:48:45 #action colindixon to reach out to the projects in the openstack guide to see if they'd be willing to migrate to readthedocs 19:48:46 https://github.com/opendaylight/docs/blob/master/docs/getting-started-guide/index.rst#getting-started-guide 19:51:16 #info colindixon asks if others think we might be able to migrate *everything* in boron, anipbu says that sounds like it will be harder to do do things beyond the getting started guide and openstack guide 19:52:37 #action anipbu to work on auto-conversion from AsciiDoc to rst 19:53:14 #link https://github.com/aria2/aria2/commit/003aaf4a09c998572e50043885be25f3b4c20bf7 one example conversion 19:53:37 #link http://hyperpolyglot.org/lightweight-markup comparison of different lightweight markup languages 19:54:29 http://pandoc.org/demos.html 19:55:12 #link http://pandoc.org/demos.html claims to support both asciidoc and rst and conversion 19:59:21 #action colindixon to create some documentation around the conversion process with a secotion about issues and workarounds 20:01:28 #endmeeting