#opendaylight-docs: docs

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

Meeting summary

  1. agenda (colindixon, 19:01:42)
    1. zxiiro to talk about using read the docs (colindixon, 19:01:53)
    2. ACTION: colindixon to try to work on getting project categorization for this page https://wiki.opendaylight.org/view/Project_list (colindixon, 19:03:30)
    3. ACTION: https://wiki.opendaylight.org/view/Docucentral colindixon to work with casey to start to populate this (colindixon, 19:03:34)
    4. ACTION: colindixon and zxiiro to follow up with trying to get auto-generated RESTCONF API documentation for Boron (colindixon, 19:04:19)

  2. zxiiro's progess on readthedocs (colindixon, 19:05:39)
    1. zxiiro ported the getting started guide from the downloads page to readthedocs using both markdown and restructuredtext (colindixon, 19:06:39)
    2. zxiiro points out restructuredtext supports things like NOTE blocks and Import blocks (colindixon, 19:07:25)
    3. zxiiro says that for the most part markdown and restructuredtext use the same syntax, but restructuredtext is more powerful (colindixon, 19:07:50)
    4. colindixon asks if there's a way to get one big HTML document? zxiiro says no, but you can get epub and PDF to download for free (colindixon, 19:09:13)
    5. colindixon asks how things are broken up into pages, zxiiro says later he'll show code, but roughly new file => new new html page (colindixon, 19:10:04)
    6. zxiiro also shows what it looks like with markdown (colindixon, 19:10:14)
    7. image syntax in markdown is different and zxiiro couldn't figure it out (colindixon, 19:10:31)
    8. zxiiro shows toctree in restructured text with table of contents and then a list of files (colindixon, 19:11:16)
    9. beau asks about the nature of this discussion, colindixon says we're looking at moving away from AsciiDoc toward readthedocs/sphinx (colindixon, 19:15:30)
    10. beau asks about why word docs wouldn't work, colindixon says that getting things working with word in git is painful, and we really want to version our docs with the code (colindixon, 19:16:52)
    11. colindixon asks how things are split up into html pages with restructured text and things (colindixon, 19:19:43)
    12. zxiiro says it's sphinx that does that, not restructuredtext (colindixon, 19:20:11)
    13. zxiiro says that it seems like there are more and more easy tools for breaking up HTML pages at the granularity you'd like (colindixon, 19:22:11)
    14. http://docutils.sourceforge.net/rst.html restructured text syntax description (colindixon, 19:23:02)
    15. http://www.sphinx-doc.org/en/stable/rest.html sphinx-restructuredtext (zxiiro, 19:25:13)
    16. zxiiro's link above to sphinx is much better for restructuredtext than the actual rst.html in the docutils project above (colindixon, 19:29:22)

  3. getting started guide (colindixon, 19:29:40)
    1. gbeauw points out that his take is that the getting started guide is really just an installation guide (colindixon, 19:30:04)
    2. gbeauw points out that really, you probably need to have what's next after installing beyond feature:install <feature-name> (colindixon, 19:31:07)
    3. gbeauw thinks what you need next is really how do you connect to devices, verify it works, etc. (colindixon, 19:31:30)
    4. CaseyODL says that we're working on trying to do example scenarios with Vagrantfiles to back it and stuff to download and play around (colindixon, 19:36:15)
    5. gbeauw says that it's beyond what he actually wants, first he doesn't really feel like he needs Vagrantfiles and they're likely going to not be appopriately tuned to his environment (colindixon, 19:36:50)
    6. colindixon notes that he is pretty sure that the kinds of things gbeauw may find the content in the per-project user guide, it might the wrong place for it and it might be a bit out of date, but it's probably there (colindixon, 19:37:41)
    7. gbeauw notes that what's there wasn't possible to make things work with thoe documentation that was there, mounting a netconf devices was nowhere in our docs (colindixon, 19:46:59)
    8. colindixon confirms that our documentation does seem to be utterly missing how to mount a netconf device, which is a huge oversight he'll look into (colindixon, 19:47:20)
    9. gbeauw notes he's not just trying to bitch, but also offering to help, which is hugely appreciated (colindixon, 19:47:46)
    10. colindixon agrees that figuring out what comes after feature:install, is what needs to get into the getting started guide next, including OpenFlow and netconf seem like great starts (colindixon, 19:48:13)
    11. ACTION: colindixon to work with gbeauw to get a list of what he thinks should go at the end of the getting started guide (colindixon, 19:49:47)


Meeting ended at 19:53:58 UTC (full logs).

Action items

  1. colindixon to try to work on getting project categorization for this page https://wiki.opendaylight.org/view/Project_list
  2. https://wiki.opendaylight.org/view/Docucentral colindixon to work with casey to start to populate this
  3. colindixon and zxiiro to follow up with trying to get auto-generated RESTCONF API documentation for Boron
  4. colindixon to work with gbeauw to get a list of what he thinks should go at the end of the getting started guide


Action items, by person

  1. colindixon
    1. colindixon to try to work on getting project categorization for this page https://wiki.opendaylight.org/view/Project_list
    2. https://wiki.opendaylight.org/view/Docucentral colindixon to work with casey to start to populate this
    3. colindixon and zxiiro to follow up with trying to get auto-generated RESTCONF API documentation for Boron
    4. colindixon to work with gbeauw to get a list of what he thinks should go at the end of the getting started guide
  2. zxiiro
    1. colindixon and zxiiro to follow up with trying to get auto-generated RESTCONF API documentation for Boron


People present (lines said)

  1. colindixon (39)
  2. odl_meetbot (5)
  3. zxiiro (2)
  4. CaseyODL (0)


Generated by MeetBot 0.1.4.