19:04:38 <colindixon> #startmeeting docs
19:04:38 <odl_meetbot> Meeting started Tue Jul 12 19:04:38 2016 UTC.  The chair is colindixon. Information about MeetBot at http://ci.openstack.org/meetbot.html.
19:04:38 <odl_meetbot> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
19:04:38 <odl_meetbot> The meeting name has been set to 'docs'
19:04:54 <colindixon> #topic agenda bashing
19:04:58 <colindixon> #link https://meetings.opendaylight.org/opendaylight-docs/2016/docs/opendaylight-docs-docs.2016-07-05-19.09.html last week's meeting minutes
19:05:08 <colindixon> #action colindixon to work with zxiiro to post instructions on how to use https to push gerrit patches
19:05:33 <colindixon> #action xinghao to push that code to opendaylight in the docs.git repostiory and also try to respect the previous file structure on conversion
19:06:41 <colindixon> #action colindixon to follow up with projects that generated the openstack content to let them know it was migrated and that we're plannig to delete the older version
19:07:18 <colindixon> #topic generic documentation review
19:08:02 <colindixon> #link https://wiki.opendaylight.org/view/Documentation colindixon updated the task list and gerrit patches links from the project facts box for docs to point to the spreadsheet for Boron and the Doc gerrit dashboard
19:11:36 <colindixon> #Info anipbu asks if he can clear the merged/abandoned patches from the spreadsheet, colindixon says that woudl be fine other than we wouldn't be able to tell if a project had no patches in Boron
19:11:47 <colindixon> #info colindixon says that you can tell priority by looking at the color of column J
19:12:24 <colindixon> #info every -1ed patch has been commented on in gerrit withink the last month
19:13:44 <colindixon> #topic migration to sphinx/rtd/reST
19:14:06 <colindixon> #link http://docs.opendaylight.org/en/latest/ now being hosted uder a CNAME of docs.opendaylight.org
19:14:31 <colindixon> #info it also looks pretty good on mobile
19:15:05 <colindixon> #link https://twitter.com/colin_dixon/status/752663809429504000 some lingering bugs
19:15:20 <colindixon> #action colindixon to open bug to fix some sizing of the top-bar
19:16:15 <colindixon> #action colindixon and/or zxiiro to fix the favicon
19:16:53 <colindixon> #topic read the docs
19:17:26 <colindixon> #Info we found out you can generate java API docs with sphinx, it looks pretty good, but it's disabled because it caused our build to take longer than 900 seconds, which then timed-out
19:18:17 <colindixon> #info it turns out it takes ~30 minutes to generate docs for just 3 projects on, which won't change
19:20:04 <colindixon> #info the three options are: 1.) get read the docs to set the time-limit to be higher, 2.) setting up our own read the docs server, or 3.) creating our own widget to add the read the docs features
19:20:12 <colindixon> #info option 2 seems best right now
19:20:46 <colindixon> #link https://twitter.com/ericholscher/status/752572876138565632 maybe we could make option 1.) easier by giving the money?
19:22:15 <colindixon> #action phrobb and zxiiro to reach out to read the docs to see if we can solve this problem with a modest amount of money
19:23:06 <colindixon> #action colindixon to note in the docs that read the docs doesn't clean the build environment between runs, which can cause really weird behavior
19:24:05 <colindixon> #info zxiiro says that generating javadoc with sphinx as part of the docs job would likely make verify jobs a lot faster
19:26:04 <colindixon> #topic possibly moving the dev/user guide to sphinx/rtd/reST in Boron
19:26:33 <colindixon> #link https://lists.opendaylight.org/pipermail/documentation/2016-July/000830.html
19:30:16 <colindixon> #info anipbu and colindixon feel that the benefits of moving almost certainly outweigh the disadvantages
19:31:20 <colindixon> #info to get consensus here, the best thing to do might be to have TWS on the migration
19:33:08 <colindixon> #action colindixon to create a page to document the benefits of reST/sphinx over AsciiDoc(tor), e.g., python, OpenStack, Linux
19:33:45 <colindixon> #link https://lwn.net/SubscriberLink/692704/76b77c4eaa4a409a/
19:34:26 <colindixon> #Info both OpenSack and the Linux Kernel have now abandoned AsciiDoc in favor or reST
19:37:09 <colindixon> https://git.opendaylight.org/gerrit/#/c/37544/
19:38:02 <colindixon> https://git.opendaylight.org/gerrit/#/q/NOT+project:docs+file:%255E.*asciidoc.*
19:38:52 <colindixon> #link https://git.opendaylight.org/gerrit/#/q/NOT+project:docs+status:merged+file:%255E.*asciidoc.* projects with asciidoc outside of the docs project
19:40:46 <colindixon> #link https://git.opendaylight.org/gerrit/#/q/-project:releng/autorelease+-project:integration/packaging+-project:docs+-project:integration/test+-project:releng/builder+-project:spectrometer+status:merged+file:%255Edocs.* proejcts with a docs/ directory that aren't using asciidoc
19:44:00 <colindixon> #info colindixon has three worries about pushing to get this done: 1.) projects that have invested heavily in AsciiDoc—both content and training—might object, 2.) doing a lot of work on docs without project-level involvement might break the feeling of ownership, 3.) a partial migration might be a pain
19:47:52 <colindixon> #info anipbu says at this point the right question to ask is "if the documentation team is willing to do all the heavy lifting, woudl any projects object to the migration from AsciiDoc to reST"
19:48:34 <colindixon> http://docs.opendaylight.org/en/latest/documentation.html#documentation-guide
19:49:10 <colindixon> http://www.sphinx-doc.org/en/stable/rest.html
19:53:47 <colindixon> #link https://git.opendaylight.org/gerrit/#/c/40647/2/docs/getting-started-guide/security_considerations.rst an example migration from AsciiDoc to reST
19:56:21 <colindixon> #info phrobb and anipbu ask if we have the time to do migration of the in-flight patches for the Boron documentation
19:57:11 <colindixon> #Info colindixon says that might be more of a pain that we want because the conversion is not likely to be fully automatic
19:59:50 <colindixon> #info phrobb wonders how many projects would be willing to migrate to reST and submit their Boron patches in reST vs. AsciiDoc so that we could tell if we could maybe migrate the rest
20:06:38 <colindixon> #info if we migrated a subset of the user/developer guide and provided at least a link to the pdfs for the rest of the projects
20:11:28 <colindixon> https://git.opendaylight.org/gerrit/#/q/topic:gsg2rst
20:16:50 <colindixon> #endmeeting