19:01:03 <colindixon> #startmeeting docs
19:01:03 <odl_meetbot> Meeting started Tue May 10 19:01:03 2016 UTC.  The chair is colindixon. Information about MeetBot at http://ci.openstack.org/meetbot.html.
19:01:03 <odl_meetbot> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
19:01:03 <odl_meetbot> The meeting name has been set to 'docs'
19:01:06 <zxiiro> vorburger: np
19:01:08 <colindixon> #topic agenda bashing
19:02:21 <zxiiro> colindixon: I'd like to discuss this at some point https://git.opendaylight.org/gerrit/38393/
19:02:38 <colindixon> #info https://git.opendaylight.org/gerrit/38393/
19:02:49 <colindixon> #info xinghao's internship
19:03:11 <colindixon> #topic infrastructure documentation
19:03:13 <colindixon> #link https://git.opendaylight.org/gerrit/#/c/38393/
19:04:02 <colindixon> #info this 1.) moves the infra documentation to readthedocs, and 2.) shows one way to do cross-project docs
19:06:03 <colindixon> #info zxiiro notes that it could be hosted by readthedocs, maven sites, or both
19:07:57 <colindixon> #info colindixon asks what happens as projects can break the docs, we should try to make it so we can detect things quickly
19:09:34 <colindixon> #Info docs could have their docs at a well-known place, e.g., /docs and then they could generate things locally as part of the normal build
19:11:06 <colindixon> #info zxiiro was looking to do things like release notes, colindixon says that's a good idea for things other than git log infomration
19:11:44 <zxiiro> https://lists.opendaylight.org/pipermail/spectrometer-dev/2016-May/000137.html
19:11:49 <colindixon> #info zxiiro says he's working on something to git log style things in spectrometer, which would close the chicken-egg problem of docs needing to push information only know after a release, before tagging the release
19:11:58 <colindixon> #link https://lists.opendaylight.org/pipermail/spectrometer-dev/2016-May/000137.html spectrometer report test
19:13:30 <colindixon> #info this all makes sense as long as it doens't result in docs being always broken the way that autorelease used to be alwasy broken
19:13:57 <colindixon> #topic Xinghao_'s internship
19:14:26 <colindixon> #info things start 5/23 and runs through 8/29
19:14:47 <colindixon> #link https://wiki.opendaylight.org/view/InternProjects:Main#Documentation_Toolchain_Improvements
19:16:13 <colindixon> #info colindixon says the goal for the internship seems like it should be to either move or get everything ready to move over to readthedocs by the end of the internship and thus the end of boron
19:16:23 <colindixon> #topic major pieces to migrate to readthedocs
19:17:08 <colindixon> #info we need is a jenkins job that builds the docs project using sphinx and fails the build on errors
19:17:18 <colindixon> #info zxiiro says we might already have this for spectrometer and could just reuse it
19:18:29 <colindixon> #info zxiiro says that what we really have a tox build job that should be able to run sphinx and that would do it and hopefully fail things as long as we have a sane tox file
19:18:40 <colindixon> #Undo
19:18:40 <odl_meetbot> Removing item from minutes: <MeetBot.ircmeeting.items.Info object at 0x2708410>
19:18:42 <colindixon> #undo
19:18:42 <odl_meetbot> Removing item from minutes: <MeetBot.ircmeeting.items.Info object at 0x27081d0>
19:18:43 <colindixon> #undo
19:18:43 <odl_meetbot> Removing item from minutes: <MeetBot.ircmeeting.items.Info object at 0x2708150>
19:18:49 <colindixon> #info 1.) we need is a jenkins job that builds the docs project using sphinx and fails the build on errors
19:18:53 <colindixon> #info zxiiro says we might already have this for spectrometer and could just reuse it
19:18:55 <colindixon> #info zxiiro says that what we really have a tox build job that should be able to run sphinx and that would do it and hopefully fail things as long as we have a sane tox file
19:19:13 <colindixon> #info we would use that as a verify job for docs (and possibly all other projects)
19:19:43 <colindixon> #info 2.) we need to (possibly with project help) convert all of our AsciiDoc to ReStructuredText
19:20:00 <colindixon> #info it's likely that a script would help with most of this, are there conversion tools?
19:20:34 <colindixon> #info 3.) as a stretch goal, allow projects to host their own docs, but make sure they can't break the world
19:20:46 <colindixon> #info that means they have their own docs-verify job for their local project
19:21:01 <colindixon> #info also they should probably run the whole docs job later to catch key things
19:21:19 <colindixon> #info zxiiro says if buidling all the docs doesn't take very long, we could just use the docs project verify job to run on all patches
19:22:03 <colindixon> #info zxiiro notes that we could only trigger builds that change the docs directory within projects
19:22:28 <colindixon> #info 4.) possilby cutomizing our readthedocs page with a better theme, etc.
19:22:47 <colindixon> #info 5.) seeing if there are tools to pull code snippets from live code in git repos
19:24:55 <colindixon> #info 6.) seeing if readthedocs can generate PDFs at a smaller granularity than all of the docs, at least for the project-level that should be doable using what we're doing, with more Makefiles
19:28:25 <colindixon> #topic questions
19:29:25 <colindixon> #info beau asks what exactly is happening, colindixon says we're moving from asciidoctor/maven/asciidoc to readthedocs/sphinx/restructuredtext
19:29:32 <colindixon> #info Xinghao_ asks if we want it to be trigger by maven
19:29:58 <colindixon> #info zxiiro says probably not since maven takes forever to load to only call a python script
19:30:58 <colindixon> #info colindixon says that's true, but it might be nice if we called that when we called mvn clean install, zxiiro says maybe not since it will fail if you don't have tox installed
19:32:00 <colindixon> #info colindixon says that the only bad thing there is that what will happen is that people will push a patch, verify will fail because of misformatted docs, and they won't be able to figure out how to reproduce it locally
19:32:35 <colindixon> #info 7.) lots of documentation about how the docs toolchain works, including messages in the docs verify job fails to give instructions
19:34:11 <colindixon> #Info 8.) figure out tooling around release notes that would help
19:45:17 <colindixon> #endmeeting