21:05:15 <rockyg> #startmeeting log_wg 21:05:15 <openstack> Meeting started Wed Feb 3 21:05:15 2016 UTC and is due to finish in 60 minutes. The chair is rockyg. Information about MeetBot at http://wiki.debian.org/MeetBot. 21:05:16 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 21:05:18 <openstack> The meeting name has been set to 'log_wg' 21:05:45 <rockyg> #topic Ops midcycle - config opts session 21:06:28 <rockyg> rbradfor, I'm socializing the work you are doing and want to get whatever info you need to help make this both as smooth and as useful as possible 21:06:52 <rbradfor> ok, I saw your session proposed in the thread 21:07:25 <rockyg> Yeah. I had proposed it earlier, but it got lost in Tom's mailbox. He thinks it's a good topic. 21:07:55 * rbradfor looking for that mail again 21:08:15 <rockyg> Also, did I mention that all the config docs got converted to RST already? It means we can make the docs happen. 21:08:44 <rockyg> The problem I see with the docs is that each project does the config opts section differently 21:09:15 <rbradfor> rockyg, do you have reference links of "different" 21:10:01 <rockyg> So, if you take Oslo as the "default" way to do them, take a look at Nova's section. Lemme find the link 21:10:50 <rbradfor> #link http://docs.openstack.org/developer/oslo.log/opts.html 21:11:11 <rbradfor> #link http://docs.openstack.org/developer/oslo.messaging/opts.html 21:11:26 <rbradfor> #link http://docs.openstack.org/developer/glance/opts.html 21:11:35 <rbradfor> here are a few developer examples 21:11:43 <rockyg> http://docs.openstack.org/liberty/config-reference/content/section_compute-config-samples.html 21:12:08 <rockyg> Ah. You're looking at the dev docs. The config ref is the one I was looking at. 21:12:10 <rbradfor> Do you know how these are generated? 21:13:32 <rockyg> I think it's mostly a cut and paste and someone on the docs team did it. 21:13:46 <rockyg> *topic Docs for config opts 21:14:02 <rockyg> #topic Docs for config opts 21:14:26 <rockyg> lemme find the responsible docs sup ptl.... 21:14:35 <rbradfor> rockyg, well if you can facilitate who in the team is doing it, and what the source copy is, that helps in validating the differences 21:15:10 <rbradfor> I am all for having the documentation driven from the oslo-config-generator and sphinxext (for RST) version. 21:16:08 <rbradfor> your example I expect is a hand crafted file 21:16:26 <rockyg> Yup. 21:17:11 <rockyg> I think we need to connect with the guy in charge of this particular doc and show him how it works. Some of the docs guys code, some don't. 21:17:54 <rbradfor> i think having an etherpad of what links we are referring to that are configuration option related (across all sources, dev, ops, conf guide) is a start 21:18:12 <rbradfor> then the source of said information, which may determine cut/paste or duplication 21:18:23 <rbradfor> of producing. 21:18:33 <rbradfor> the goal of inconsistencies is to have only source of information. 21:18:43 <rbradfor> of removing .. 21:20:24 <rockyg> you wanna create the etherpad, or should I? We've got lots of links and I just got the link to the config guide docs team 21:20:49 <rbradfor> I think it should probably be part of your config guide docs. 21:21:08 <rbradfor> again, identifying all the different sources in documentation, e.g. a projects config 21:21:33 <rbradfor> and then working on reducing the varying versions to be consistent 21:21:47 <rockyg> Yah. But etherpad leads to config guide doc, not part of..... 21:22:19 <rockyg> I can certainly collect all the places I can find, categorize and have it ready for the ops midcycle... 21:23:44 <rbradfor> well if your trying to present a case to have a config guide, it helps to source the existing versions of document for reference. you want to justify why each existing docs are incomplete or complex or duplicating 21:24:32 <rockyg> There already is the config ref. do we want another doc or just better organize the current, with more info and single source of truth? 21:24:53 <rbradfor> I can certainly help in ensuring configuration documentation (and sample config files) get generated, and hopefully we can get projects to be consistent about it. 21:25:14 <rockyg> But then, we'd also have to make sure that dev docs match user docs, too. 21:25:18 <rbradfor> I thought you were creating a new config reference. Does it exist now? 21:25:44 <rockyg> Yup. Thats the first link I pointed you to with the sample configs 21:26:21 <rockyg> And here's the link to the team: https://wiki.openstack.org/wiki/Documentation/ConfigRef 21:27:23 <rockyg> In fact, there's even a todo to get the opts section(s) better. 21:28:24 <rbradfor> so you mentioned "Convert the Configuration Reference from DocBook to RST" is done. 21:28:42 <rockyg> Yup. 21:28:58 <rockyg> I saw that in one of the What's Up Doc emails. 21:29:28 <rockyg> Which means that your generator stuff can just slide in there.... 21:29:41 <rbradfor> ok, so looking at blueprint at https://blueprints.launchpad.net/openstack-manuals/+spec/config-ref-rst and an example recent review at https://review.openstack.org/#/c/259889/ 21:30:18 <rbradfor> we are in openstack/openstack-manuals repo and config-reference 21:31:10 <rbradfor> I don't see a gate that provides a link to physically show what the changes look like. 21:31:17 <rockyg> Hmm. 21:31:46 <rbradfor> let me give you an example I understand 21:32:01 <rbradfor> Add Configuration Options to Glance Developer Docs - https://review.openstack.org/#/c/270920/ 21:32:20 <rbradfor> You can see the proposed documentation generated (as in review) at http://docs-draft.openstack.org/20/270920/4/check/gate-glance-docs/0e8ef17//doc/build/html/ 21:32:45 <rbradfor> when that review is merged, this becomes http://docs.openstack.org/developer/glance/ 21:33:00 <rbradfor> I do not know the workflow of openstack-manuals 21:33:41 <rockyg> so, you can see a gate build I think.....gate-openstack-manuals-tox-doc-publish-checkbuild in the list of jobs, but the link is gone 21:34:08 <rbradfor> I saw that 21:35:40 <rockyg> And the wiki points to kilo stuff....hmm....Lemme track back to main docs wiki page 21:35:49 <rbradfor> Liberty -- http://docs.openstack.org/liberty/config-reference/content/config_overview.html 21:35:55 <rbradfor> mitaka links don't seem to work 21:37:24 <rockyg> So, there are directions to build the "patch" locally: http://docs.openstack.org/contributor-guide/docs-review.html 21:38:52 <rockyg> It's down a bit on the page. I'm at home so don't have the setup for repos an builds.... 21:39:29 <rbradfor> do Mitaka docs get published on the site before it's officially released? 21:41:18 <rockyg> No. Yhey put the links up at release, which is about a week after code release. But I think they have internal links for devs to review sometime after M3 21:42:31 <rbradfor> ok, well what can I do from the developer docs perspective to generate docs that are incorporated. 21:43:23 <rockyg> Ok. Also found this note on the docs wiki: "The Configuration Reference and the Networking Guide are versioned, all other guides are continuously published." 21:43:39 <rbradfor> and as I look back at links, how does this also relate to the Openstack Operations Guide - http://docs.openstack.org/openstack-ops/content/ 21:44:13 <rbradfor> maybe that's totally separate 21:44:35 <rockyg> I'll see if I can connect with Gauvain and maybe get some sync up happening. I'll put togehter an etherpad with all these links, plus others, and let you know.... 21:44:47 <rbradfor> There is a "Configuration Reference" link on the home page ,http://docs.openstack.org/ it goes to http://docs.openstack.org/liberty/config-reference/content/ 21:45:24 <rockyg> Yup. That's the versioned copy. 21:45:26 <rbradfor> so, if the conversion to RST is complete, the question is does it look a lot like the Liberty version? 21:45:54 <rbradfor> and if the content is not being generated, how is being sourced, e.g. cut/paste as you proposed 21:46:25 <rbradfor> and how can we then better generate the configuration options and configuration sample files. 21:46:58 <rbradfor> How it's then ordered or categorized into the configuration guide, e.g. a global logging session is something for the docs team to decide on, hopefully based on your recommendations 21:47:22 <rockyg> Here's an interesting link on the docs wiki: http://git.openstack.org/cgit/openstack/openstack-doc-tools/tree/autogenerate_config_docs/README.rst 21:48:26 <rbradfor> again, I'm not familar with the docs team way of doing things. 21:49:21 <rockyg> Yeahl I can use the ops midcycle to find out what besides logging they want in a more "global' chapter. I'm not enough into docs either. I fixed a bug or two there, but I just edited the xml back then and left the rest to the docs team. 21:50:27 <rockyg> I'll hook up with them, show them the dev config doc stuff and see where it goes from there. Might have the guy for config doc come to one of our meetings. 21:50:38 <rockyg> Like to get this in Mitaka version. 21:52:33 <rockyg> How about I put together an etherpad, talk to Gauvain, have him review the etherpad, then you, and see if we can send to the dev mailing list to get comments, get them to do their part in their projects? 21:53:35 <rbradfor> I think verifying the source of information used in the config guide first is important. 21:53:52 <rockyg> OK. I'll connect with docs folks. 21:54:28 <rockyg> Right after I put all these links on an etherpad for reference. 21:55:17 <rockyg> #action Rocky to collect up config links that reference config opts and circle back to Docs to see how docs generate their config info 21:55:53 <rockyg> Good enough for today? 21:55:59 <rbradfor> sounds good 21:56:20 <rockyg> #topic Open discussion 21:56:28 <rockyg> I got nuthin else. 21:56:52 <rbradfor> no, still working on removing some deprecated options (so they get removed from the docs) 21:57:19 <rockyg> OK. I'll let you get back to it, then. It will be nice to see some of them go away. 21:57:26 <rockyg> Thanks so much! 21:57:30 <rockyg> #endmeeting