#opendaylight-docs: docs

Meeting started by colindixon at 19:12:41 UTC (full logs).

Meeting summary

  1. getting started guide (colindixon, 19:12:52)
    1. phrobb_ asks if we could could get Beau from T-mobilie engaged in docs, he wants to work on the getting started guide (colindixon, 19:23:59)
    2. https://read-the-docs.readthedocs.org/en/latest/getting_started.html (colindixon, 19:24:00)
    3. https://read-the-docs.readthedocs.org/en/latest/builds.html (colindixon, 19:24:31)
    4. colindixon notes that there is no real authoritative copy of the gettinger started guide right now (colindixon, 19:30:51)
    5. the closest thing is Denise's google doc (colindixon, 19:31:03)
    6. colin has a clone of that which has the tables listed as images from the AsciiDoc and is published as HTML so we had something to launch with (colindixon, 19:31:37)
    7. Melissa and the web team should be converting it to HTML for the main page (colindixon, 19:31:47)
    8. https://freeseer.readthedocs.org/en/latest/ (zxiiro, 19:32:05)
    9. https://docs.djangoproject.com/en/1.7/ref/clickjacking/ (colindixon, 19:34:02)
    10. https://docs.readthedocs.org/en/latest/alternate_domains.html (zxiiro, 19:37:01)
    11. the HTML version for the getting started guide hasn't yet supplanted Colin's published google doc on the dowloads page (colindixon, 19:38:17)
    12. colindixon says he hasn't migrated the authoritative copy to git yet because he thought we might consider moving away from AsciiDoc (colindixon, 19:38:46)

  2. read the docs (colindixon, 19:38:52)
    1. http://readthedocs.org/ (colindixon, 19:38:57)
    2. zxiiro says he's used it in the past and likes it (colindixon, 19:39:43)
    3. it takes documentation in MarkDown and reStrucgturedText, but seems to rely on Sphinx to genearte the docs while readTheDocs basically just provides the web front end (colindixon, 19:41:06)
    4. https://docs.djangoproject.com/en/1.7/ref/clickjacking/ an example of something using read the docs (colindixon, 19:41:20)
    5. note that it flags things as as out-of-date at the top (colindixon, 19:41:35)
    6. it also lets you jump between versions (presumably git branches) (colindixon, 19:41:46)
    7. it also generates PDF versions of the full docs (colindixon, 19:41:55)
    8. lets you search through things (colindixon, 19:41:59)
    9. one thing to figure out if we can pull in live code snippets from java, it does python for now (colindixon, 19:43:24)
    10. colindixon notes that we only have a prototype version of that for AsciiDoc and it's not very real (colindixon, 19:44:05)
    11. zxiiro says that you could probably pull in docs from other git repos with a sphinx script, it could clone all projects and then pull them together (colindixon, 19:45:53)
    12. colindixon notes that all of our docs are in one project so the above would just be icing on the cake (colindixon, 19:46:38)

  3. next steps (colindixon, 19:46:39)
    1. we'd presumably want to prototype it with something (colindixon, 19:46:55)
    2. it sounds like creating a cloned version of the docs repo just using the getting started guide might be a good idea (colindixon, 19:48:21)
    3. colindixon says his plan would be to clone docs, strip out everything but the getting started guide, converting the asciidoc to RST or markdown, doing that across branches and tags, then getting sphix/readthedocs to eat and publish it (colindixon, 19:52:30)
    4. risks would be making everyone move to RST or markdown instead of AsciiDoc, but that would generally be good except for the painful one-time migration (colindixon, 19:53:16)
    5. ACTION: zxiiro volunteers to try to get *something* set up (colindixon, 19:53:33)
    6. ACTION: zxiiro to document thigns a bit from the project's perspective, e.g., what migration would be required and how would it be different post-migratoin (colindixon, 19:55:26)


Meeting ended at 19:57:19 UTC (full logs).

Action items

  1. zxiiro volunteers to try to get *something* set up
  2. zxiiro to document thigns a bit from the project's perspective, e.g., what migration would be required and how would it be different post-migratoin


Action items, by person

  1. zxiiro
    1. zxiiro volunteers to try to get *something* set up
    2. zxiiro to document thigns a bit from the project's perspective, e.g., what migration would be required and how would it be different post-migratoin


People present (lines said)

  1. colindixon (37)
  2. odl_meetbot (5)
  3. zxiiro (2)
  4. phrobb_ (1)


Generated by MeetBot 0.1.4.