#opendaylight-docs: docs

Meeting started by colindixon at 19:04:38 UTC (full logs).

Meeting summary

  1. agenda bashing (colindixon, 19:04:54)
    1. https://meetings.opendaylight.org/opendaylight-docs/2016/docs/opendaylight-docs-docs.2016-07-05-19.09.html last week's meeting minutes (colindixon, 19:04:58)
    2. ACTION: colindixon to work with zxiiro to post instructions on how to use https to push gerrit patches (colindixon, 19:05:08)
    3. ACTION: xinghao to push that code to opendaylight in the docs.git repostiory and also try to respect the previous file structure on conversion (colindixon, 19:05:33)
    4. 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 (colindixon, 19:06:41)

  2. generic documentation review (colindixon, 19:07:18)
    1. 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 (colindixon, 19:08:02)
    2. 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 (colindixon, 19:11:36)
    3. colindixon says that you can tell priority by looking at the color of column J (colindixon, 19:11:47)
    4. every -1ed patch has been commented on in gerrit withink the last month (colindixon, 19:12:24)

  3. migration to sphinx/rtd/reST (colindixon, 19:13:44)
    1. http://docs.opendaylight.org/en/latest/ now being hosted uder a CNAME of docs.opendaylight.org (colindixon, 19:14:06)
    2. it also looks pretty good on mobile (colindixon, 19:14:31)
    3. https://twitter.com/colin_dixon/status/752663809429504000 some lingering bugs (colindixon, 19:15:05)
    4. ACTION: colindixon to open bug to fix some sizing of the top-bar (colindixon, 19:15:20)
    5. ACTION: colindixon and/or zxiiro to fix the favicon (colindixon, 19:16:15)

  4. read the docs (colindixon, 19:16:53)
    1. 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 (colindixon, 19:17:26)
    2. it turns out it takes ~30 minutes to generate docs for just 3 projects on, which won't change (colindixon, 19:18:17)
    3. 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 (colindixon, 19:20:04)
    4. option 2 seems best right now (colindixon, 19:20:12)
    5. https://twitter.com/ericholscher/status/752572876138565632 maybe we could make option 1.) easier by giving the money? (colindixon, 19:20:46)
    6. 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 (colindixon, 19:22:15)
    7. 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 (colindixon, 19:23:06)
    8. zxiiro says that generating javadoc with sphinx as part of the docs job would likely make verify jobs a lot faster (colindixon, 19:24:05)

  5. possibly moving the dev/user guide to sphinx/rtd/reST in Boron (colindixon, 19:26:04)
    1. https://lists.opendaylight.org/pipermail/documentation/2016-July/000830.html (colindixon, 19:26:33)
    2. anipbu and colindixon feel that the benefits of moving almost certainly outweigh the disadvantages (colindixon, 19:30:16)
    3. to get consensus here, the best thing to do might be to have TWS on the migration (colindixon, 19:31:20)
    4. ACTION: colindixon to create a page to document the benefits of reST/sphinx over AsciiDoc(tor), e.g., python, OpenStack, Linux (colindixon, 19:33:08)
    5. https://lwn.net/SubscriberLink/692704/76b77c4eaa4a409a/ (colindixon, 19:33:45)
    6. both OpenSack and the Linux Kernel have now abandoned AsciiDoc in favor or reST (colindixon, 19:34:26)
    7. https://git.opendaylight.org/gerrit/#/c/37544/ (colindixon, 19:37:09)
    8. https://git.opendaylight.org/gerrit/#/q/NOT+project:docs+file:%255E.*asciidoc.* (colindixon, 19:38:02)
    9. https://git.opendaylight.org/gerrit/#/q/NOT+project:docs+status:merged+file:%255E.*asciidoc.* projects with asciidoc outside of the docs project (colindixon, 19:38:52)
    10. 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 (colindixon, 19:40:46)
    11. 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 (colindixon, 19:44:00)
    12. 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" (colindixon, 19:47:52)
    13. http://docs.opendaylight.org/en/latest/documentation.html#documentation-guide (colindixon, 19:48:34)
    14. http://www.sphinx-doc.org/en/stable/rest.html (colindixon, 19:49:10)
    15. https://git.opendaylight.org/gerrit/#/c/40647/2/docs/getting-started-guide/security_considerations.rst an example migration from AsciiDoc to reST (colindixon, 19:53:47)
    16. phrobb and anipbu ask if we have the time to do migration of the in-flight patches for the Boron documentation (colindixon, 19:56:21)
    17. colindixon says that might be more of a pain that we want because the conversion is not likely to be fully automatic (colindixon, 19:57:11)
    18. 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 (colindixon, 19:59:50)
    19. 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 (colindixon, 20:06:38)
    20. https://git.opendaylight.org/gerrit/#/q/topic:gsg2rst (colindixon, 20:11:28)


Meeting ended at 20:16:50 UTC (full logs).

Action items

  1. colindixon to work with zxiiro to post instructions on how to use https to push gerrit patches
  2. xinghao to push that code to opendaylight in the docs.git repostiory and also try to respect the previous file structure on conversion
  3. 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
  4. colindixon to open bug to fix some sizing of the top-bar
  5. colindixon and/or zxiiro to fix the favicon
  6. phrobb and zxiiro to reach out to read the docs to see if we can solve this problem with a modest amount of money
  7. colindixon to note in the docs that read the docs doesn't clean the build environment between runs, which can cause really weird behavior
  8. colindixon to create a page to document the benefits of reST/sphinx over AsciiDoc(tor), e.g., python, OpenStack, Linux


Action items, by person

  1. colindixon
    1. colindixon to work with zxiiro to post instructions on how to use https to push gerrit patches
    2. 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
    3. colindixon to open bug to fix some sizing of the top-bar
    4. colindixon and/or zxiiro to fix the favicon
    5. colindixon to note in the docs that read the docs doesn't clean the build environment between runs, which can cause really weird behavior
    6. colindixon to create a page to document the benefits of reST/sphinx over AsciiDoc(tor), e.g., python, OpenStack, Linux
  2. UNASSIGNED
    1. xinghao to push that code to opendaylight in the docs.git repostiory and also try to respect the previous file structure on conversion
    2. phrobb and zxiiro to reach out to read the docs to see if we can solve this problem with a modest amount of money


People present (lines said)

  1. colindixon (48)
  2. odl_meetbot (3)


Generated by MeetBot 0.1.4.