#opendaylight-docs: docs

Meeting started by colindixon at 19:01:03 UTC (full logs).

Meeting summary

  1. agenda bashing (colindixon, 19:01:08)
    1. https://git.opendaylight.org/gerrit/38393/ (colindixon, 19:02:38)
    2. xinghao's internship (colindixon, 19:02:49)

  2. infrastructure documentation (colindixon, 19:03:11)
    1. https://git.opendaylight.org/gerrit/#/c/38393/ (colindixon, 19:03:13)
    2. this 1.) moves the infra documentation to readthedocs, and 2.) shows one way to do cross-project docs (colindixon, 19:04:02)
    3. zxiiro notes that it could be hosted by readthedocs, maven sites, or both (colindixon, 19:06:03)
    4. colindixon asks what happens as projects can break the docs, we should try to make it so we can detect things quickly (colindixon, 19:07:57)
    5. 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 (colindixon, 19:09:34)
    6. zxiiro was looking to do things like release notes, colindixon says that's a good idea for things other than git log infomration (colindixon, 19:11:06)
    7. https://lists.opendaylight.org/pipermail/spectrometer-dev/2016-May/000137.html (zxiiro, 19:11:44)
    8. 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 (colindixon, 19:11:49)
    9. https://lists.opendaylight.org/pipermail/spectrometer-dev/2016-May/000137.html spectrometer report test (colindixon, 19:11:58)
    10. 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 (colindixon, 19:13:30)

  3. Xinghao_'s internship (colindixon, 19:13:57)
    1. things start 5/23 and runs through 8/29 (colindixon, 19:14:26)
    2. https://wiki.opendaylight.org/view/InternProjects:Main#Documentation_Toolchain_Improvements (colindixon, 19:14:47)
    3. 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 (colindixon, 19:16:13)

  4. major pieces to migrate to readthedocs (colindixon, 19:16:23)
    1. 1.) we need is a jenkins job that builds the docs project using sphinx and fails the build on errors (colindixon, 19:18:49)
    2. zxiiro says we might already have this for spectrometer and could just reuse it (colindixon, 19:18:53)
    3. 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 (colindixon, 19:18:55)
    4. we would use that as a verify job for docs (and possibly all other projects) (colindixon, 19:19:13)
    5. 2.) we need to (possibly with project help) convert all of our AsciiDoc to ReStructuredText (colindixon, 19:19:43)
    6. it's likely that a script would help with most of this, are there conversion tools? (colindixon, 19:20:00)
    7. 3.) as a stretch goal, allow projects to host their own docs, but make sure they can't break the world (colindixon, 19:20:34)
    8. that means they have their own docs-verify job for their local project (colindixon, 19:20:46)
    9. also they should probably run the whole docs job later to catch key things (colindixon, 19:21:01)
    10. 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 (colindixon, 19:21:19)
    11. zxiiro notes that we could only trigger builds that change the docs directory within projects (colindixon, 19:22:03)
    12. 4.) possilby cutomizing our readthedocs page with a better theme, etc. (colindixon, 19:22:28)
    13. 5.) seeing if there are tools to pull code snippets from live code in git repos (colindixon, 19:22:47)
    14. 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 (colindixon, 19:24:55)

  5. questions (colindixon, 19:28:25)
    1. beau asks what exactly is happening, colindixon says we're moving from asciidoctor/maven/asciidoc to readthedocs/sphinx/restructuredtext (colindixon, 19:29:25)
    2. Xinghao_ asks if we want it to be trigger by maven (colindixon, 19:29:32)
    3. zxiiro says probably not since maven takes forever to load to only call a python script (colindixon, 19:29:58)
    4. 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 (colindixon, 19:30:58)
    5. 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 (colindixon, 19:32:00)
    6. 7.) lots of documentation about how the docs toolchain works, including messages in the docs verify job fails to give instructions (colindixon, 19:32:35)
    7. 8.) figure out tooling around release notes that would help (colindixon, 19:34:11)


Meeting ended at 19:45:17 UTC (full logs).

Action items

  1. (none)


People present (lines said)

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


Generated by MeetBot 0.1.4.