| *** dims__ has joined #openstack-sprint | 10:28 | |
| dims__ | folks, we'll be using this channel for Oslo Documentation sprint today and tomorrow | 10:29 |
|---|---|---|
| *** cdelatte has joined #openstack-sprint | 11:28 | |
| dims__ | Etherpad is here - https://etherpad.openstack.org/p/oslo-liberty-virtual-doc-sprint | 11:39 |
| dims__ | first from me - https://review.openstack.org/227245 | 11:50 |
| *** rfolco has joined #openstack-sprint | 12:02 | |
| *** haypo has joined #openstack-sprint | 12:13 | |
| dims__ | very easy to add https://review.openstack.org/227245 to other projects - mechanical changes... | 12:13 |
| *** dims__ has quit IRC | 12:19 | |
| *** dims_ has joined #openstack-sprint | 12:20 | |
| *** cdelatte has quit IRC | 12:31 | |
| dhellmann | good morning | 12:31 |
| *** bknudson1 has joined #openstack-sprint | 12:32 | |
| dhellmann | dims_: is gerrit slow for you this morning? | 12:37 |
| bknudson1 | gerrit it slow | 12:38 |
| bknudson1 | gerrit is slow | 12:38 |
| bknudson1 | it was slowish yesterday | 12:38 |
| dhellmann | hi, bknudson1 | 12:40 |
| bknudson1 | dhellmann: hi. | 12:40 |
| bknudson1 | this is going to be painful with gerrit so slow | 12:46 |
| dhellmann | yeah | 12:47 |
| *** tjcocozz has joined #openstack-sprint | 12:48 | |
| *** cdelatte has joined #openstack-sprint | 13:03 | |
| dhellmann | adding source link to documentation sidebars: https://review.openstack.org/227299 | 13:26 |
| bknudson1 | dhellmann: loading... | 13:27 |
| bknudson1 | dhellmann: it's fixed | 13:40 |
| dhellmann | bknudson1: ah, much better now | 13:41 |
| *** cdelatte has quit IRC | 13:54 | |
| bknudson1 | when do we start? | 14:03 |
| bknudson1 | maybe it's just me. | 14:03 |
| dhellmann | bknudson1: I'm working! | 14:06 |
| dhellmann | bknudson1: https://review.openstack.org/227322 | 14:06 |
| dhellmann | bknudson1: although the glance team is meeting now... | 14:06 |
| bknudson1 | I can take a look at that one. | 14:08 |
| *** dims__ has joined #openstack-sprint | 14:11 | |
| dims__ | bknudson1: dhellmann: am back now | 14:12 |
| *** dims_ has quit IRC | 14:14 | |
| bknudson1 | I've got some doc changes that are ready for review, starting with https://review.openstack.org/#/c/226042/ | 14:20 |
| dims__ | bknudson1: dhellmann gets first dibs on that auto generate. i tend to favor it and i remember dhellmann preferred explicit | 14:23 |
| bknudson1 | if you go explicit then somebody has to keep it up to date. | 14:23 |
| dims__ | right | 14:24 |
| *** cdelatte has joined #openstack-sprint | 14:29 | |
| *** mrmartin has joined #openstack-sprint | 14:47 | |
| bknudson1 | Proposed fix for a doc bug: https://review.openstack.org/#/c/227346/ | 14:50 |
| *** cdelatte has quit IRC | 14:51 | |
| bknudson1 | bug 1370439 | 14:51 |
| openstack | bug 1370439 in oslo.log "log_config_append disables existing loggers" [Low,In progress] https://launchpad.net/bugs/1370439 - Assigned to Brant Knudson (blk-u) | 14:51 |
| *** cdelatte has joined #openstack-sprint | 14:56 | |
| dims__ | Bug fix - documentation for DictOpt - https://review.openstack.org/227353 | 14:57 |
| bknudson1 | dims__: I'll take a look. | 14:58 |
| dims__ | thanks bknudson1 | 15:07 |
| *** cdelatte has quit IRC | 15:11 | |
| dhellmann | bknudson1: I've updated https://review.openstack.org/#/c/227322/ | 15:22 |
| bknudson1 | dhellmann: looking... | 15:23 |
| bknudson1 | fancy! | 15:23 |
| bknudson1 | that's funny... what would be the point of stevedore if you had to match the module to the entrypoint? | 15:33 |
| dhellmann | bknudson1: yes, well, apparently that's not so obvious to everyone else :-) | 15:33 |
| dhellmann | bknudson1: left a note about the toctree on https://review.openstack.org/#/c/226042/4 | 15:37 |
| bknudson1 | dhellmann: ok, let me look at it. I could get to the modules using the modindex. | 15:38 |
| dhellmann | bknudson1: ah, good point, but they don't show up in the table of contents and I suspect most folks are going to be looking there | 15:39 |
| bknudson1 | dhellmann: ah, will look at it. | 15:39 |
| * dhellmann takes a break to pick up lunch | 15:47 | |
| bknudson1 | dhellmann: update https://review.openstack.org/#/c/226042/ -- including the toc for the autoindex looked ok and useful to me. | 15:59 |
| *** cdelatte has joined #openstack-sprint | 16:08 | |
| *** cdelatte has quit IRC | 16:17 | |
| *** cdelatte has joined #openstack-sprint | 16:23 | |
| tjcocozz | For atomaton would you like to see another finite state machine example? | 16:27 |
| tjcocozz | Do you have anything in mind? | 16:27 |
| tjcocozz | Here are the current examples if you are wondering: http://docs.openstack.org/developer/automaton/examples.html | 16:30 |
| dhellmann | tjcocozz: I think some of the other libraries probably need more attention than automaton | 16:48 |
| tjcocozz | dhellman: okay, I am out of the office after lunch. Point me where you need me, I have all day tomorrow | 16:50 |
| dims__ | tjcocozz: we're using this etherpad - https://etherpad.openstack.org/p/oslo-liberty-virtual-doc-sprint | 16:50 |
| dhellmann | tjcocozz: I'm trying to collect some suggestions in the etherpad dims started: https://etherpad.openstack.org/p/oslo-liberty-virtual-doc-sprint | 16:50 |
| tjcocozz | yup i'm on it. oslo.policy grammar fixes sound good? | 16:52 |
| dhellmann | tjcocozz: yeah, it would be good to have some examples how how that language works | 16:53 |
| dhellmann | tjcocozz: people figure it out, so there must be something somewhere, maybe in one of the doc team manuals? | 16:53 |
| tjcocozz | dhellmann: I will work on it tomorrow. Thanks for the help | 16:56 |
| dhellmann | tjcocozz: great, thanks! | 16:56 |
| *** cdelatte has quit IRC | 17:25 | |
| *** cdelatte has joined #openstack-sprint | 17:40 | |
| *** harlowja has joined #openstack-sprint | 17:41 | |
| harlowja | whats up folks! | 17:41 |
| bknudson1 | harlowja: we were waiting for you | 17:43 |
| harlowja | lol | 17:43 |
| harlowja | ya, the 101 (ca highway) was slow | 17:43 |
| harlowja | stupid traffic, ha | 17:44 |
| bknudson1 | I lived on 101 for a while (oregon, where it wasn't busy) | 17:44 |
| harlowja | :-/ | 17:44 |
| harlowja | ok, all docs are fixed? | 17:45 |
| harlowja | lol | 17:45 |
| dims__ | we need you get started harlowja :) | 17:45 |
| harlowja | someting i was thinking of | 17:46 |
| harlowja | https://github.com/openstack/taskflow/blob/master/taskflow/tests/test_examples.py was going to be 'generalized' so that oslo.messagin could use it | 17:46 |
| * harlowja forget whatever happened to that effort | 17:46 | |
| harlowja | https://review.openstack.org/#/c/140318/ ? | 17:46 |
| harlowja | dims__ do u know 'Oleksii Zamiatin' ? | 17:46 |
| dims__ | harlowja: da | 17:46 |
| dims__ | harlowja: he is writing the zmq o.m driver | 17:47 |
| harlowja | k | 17:47 |
| harlowja | guess zmq > examples right now | 17:47 |
| harlowja | another question for folks | 17:52 |
| harlowja | http://docs.openstack.org/developer/taskflow/jobs.html#id1 | 17:52 |
| harlowja | the code docs there include link to [source] | 17:52 |
| harlowja | http://docs.openstack.org/developer/oslo.utils/api/encodeutils.html#oslo_utils.encodeutils.exception_to_unicode | 17:52 |
| harlowja | that one for example doesn't link to [source] | 17:52 |
| harlowja | do people think we should all just link to source (its a small sphinx change/config setting) | 17:53 |
| harlowja | pretty sure https://github.com/openstack/taskflow/blob/master/doc/source/conf.py#L17 (that line) | 17:53 |
| harlowja | i sorta like being able to see the source if i want on the doc page, but others might not | 17:53 |
| bknudson1 | it's work to link to source? | 17:54 |
| harlowja | adding one line to conf.py | 17:54 |
| harlowja | otherwise no | 17:54 |
| harlowja | but depends on your defintion of work :-P | 17:55 |
| harlowja | (do note that it doesn't link to git) | 17:55 |
| bknudson1 | I'm not a fan of linking to source. | 17:55 |
| bknudson1 | it embeds the source? | 17:55 |
| harlowja | seems so | 17:56 |
| bknudson1 | that's pretty common | 17:56 |
| bknudson1 | is this really useful: http://docs.openstack.org/developer/taskflow/_modules/taskflow/jobs/backends/impl_zookeeper.html#ZookeeperJob.lock_path ? | 17:56 |
| harlowja | for person that is clicking on docs and just wants to know, i guess | 17:56 |
| harlowja | for super-duper program like bknudson1 maybe not | 17:57 |
| harlowja | *progammer, not program | 17:57 |
| harlowja | (don't think u are a program) | 17:57 |
| bknudson1 | I'm always looking at source code, but that's usually because the docs are inadequate | 17:57 |
| harlowja | :-P | 17:57 |
| bknudson1 | and it usually takes a lot more than just looking at the function | 17:58 |
| harlowja | i always take apart my engine when i need to change the oil, cause the docs are inadequate, lol | 17:58 |
| harlowja | *car engine | 17:58 |
| harlowja | haha | 17:58 |
| bknudson1 | if you had a tesla ... | 17:58 |
| harlowja | :-P | 17:58 |
| harlowja | anyways, just wanted to see if people think we should just either include links to source, or remove it, or something else :-P | 17:59 |
| harlowja | was pretty sure opinions would vary, but meh, who knows | 18:00 |
| bknudson1 | harlowja: does the doc build take a lot longer? | 18:00 |
| harlowja | i don't notice any time difference | 18:01 |
| harlowja | sphinx afaik has to scan all the code to build the api docs anyway | 18:01 |
| *** mrmartin has quit IRC | 18:01 | |
| harlowja | but if u have a 386 it might be slower | 18:01 |
| harlowja | but ya, u should upgrade to 486 | 18:01 |
| * harlowja just saying | 18:01 | |
| bknudson1 | I ask because when I'm fixing up docs I often wind up building 4-5 times to get it right and if it slows a lot that would impact me. | 18:02 |
| bknudson1 | I can never guess what it's going to look like when it's rendered | 18:02 |
| harlowja | i've never noticed any change | 18:03 |
| harlowja | ya, i build everything locally -> a htdocs folder, that i can then view it on | 18:03 |
| harlowja | *usually* do that | 18:03 |
| harlowja | ie sphinx-build doc/source/ /home/y/share/htdocs/taskflow && doc8 doc/source/ ... | 18:03 |
| harlowja | and profit | 18:03 |
| harlowja | then view from browser to said machine hosting htdocs | 18:04 |
| bknudson1 | doc8? | 18:04 |
| harlowja | https://github.com/stackforge/doc8/ | 18:04 |
| harlowja | partially created by me, ripped it out from taskflow tools folder (where it was born) | 18:04 |
| bknudson1 | we need to get that in the gate | 18:04 |
| harlowja | most projects i think are using it | 18:04 |
| harlowja | oslo could adopt it | 18:04 |
| harlowja | :-P | 18:05 |
| harlowja | but https://github.com/openstack/magnum/blob/master/tox.ini#L40 | 18:05 |
| harlowja | *no but | 18:05 |
| harlowja | pretty sure thats common in most places (not everywhere) | 18:05 |
| harlowja | *varies somewhat based on project | 18:05 |
| harlowja | https://github.com/openstack/taskflow/blob/master/tox.ini#L59 (what taskflow does) | 18:06 |
| harlowja | 'sphinx-build -b doctest doc/source doc/build' is something we should probably also do in common | 18:06 |
| harlowja | ^ tests any inline doc code | 18:06 |
| harlowja | http://sphinx-doc.org/ext/doctest.html | 18:06 |
| harlowja | *not everyone is using that (taskflow does) | 18:07 |
| harlowja | arg doc @ https://pypi.python.org/pypi/doc8 not looking right, (me) must of busted it somehow | 18:08 |
| bknudson1 | I'll add implementing doc8 in keystone projects to my list | 18:10 |
| harlowja | xcool | 18:10 |
| harlowja | *cool | 18:10 |
| bknudson1 | it's a long list so don't expect it any time soon | 18:10 |
| harlowja | some people don't put it under the py27 tox env though, so it won't be gated on | 18:10 |
| harlowja | putting it under a [docs] env doesn't get automatically ran afaik | 18:10 |
| harlowja | i think https://github.com/openstack/taskflow/blob/master/tox.ini#L59 is the right way (but i might be wrong) | 18:11 |
| harlowja | ^ runs testr, checks the doctest in doc(s), runs doc8 | 18:11 |
| bknudson1 | keystone gates on -docs | 18:11 |
| harlowja | k | 18:11 |
| *** cdelatte has quit IRC | 18:11 | |
| bknudson1 | and we have warnerrors in [pbr] so that catches bad rst | 18:11 |
| harlowja | cool | 18:12 |
| bknudson1 | does doc8 catch :raises: something ? | 18:12 |
| harlowja | doctest is the other one i think people forget | 18:12 |
| harlowja | unsure, it might | 18:12 |
| bknudson1 | rather than :raises something: | 18:12 |
| harlowja | thats code level docs right? | 18:12 |
| bknudson1 | yes, it would be in the docstring | 18:12 |
| harlowja | ya, doc8 is just validating some stuff on rst files, txt files | 18:13 |
| bknudson1 | oh, I don't care about that | 18:13 |
| harlowja | not parsing code trees/code | 18:13 |
| bknudson1 | I want to validate docstrings | 18:13 |
| harlowja | its probably possibly | 18:13 |
| harlowja | just never tried that | 18:13 |
| harlowja | doc8 right now is just using https://github.com/twolfson/restructuredtext-lint (which helps do basic linting) | 18:14 |
| harlowja | but its not afaik (yet?) getting into the nitty of activating sphinx and extracting code docs... | 18:14 |
| *** cdelatte has joined #openstack-sprint | 18:14 | |
| harlowja | it could, just untaggling sphinx and figuring out how that all works is a pita, lol | 18:14 |
| harlowja | *using https://github.com/twolfson/restructuredtext-lint (and docutils from what i remember) | 18:15 |
| bknudson1 | if you run doc8 after sphinx you should be able to look at doc/source/api | 18:15 |
| harlowja | possibly | 18:15 |
| harlowja | sounds like doc8 v.next :-P | 18:15 |
| bknudson1 | I just realized maybe the docs job doesn't run tox -e docs, but instead tox -e venv sphinx whatever | 18:16 |
| bknudson1 | harlowja: doc9 | 18:16 |
| harlowja | bknudson1 ya, afaik its `tox -e venv` | 18:16 |
| harlowja | doc9 works for me, lol | 18:16 |
| harlowja | i did try to figure out how sphinx was doing all it stuff at one time | 18:16 |
| harlowja | but it got complicated real quick | 18:16 |
| harlowja | ha | 18:16 |
| bknudson1 | if it's just importing and looking at __doc__ ? | 18:16 |
| harlowja | * https://github.com/twolfson/restructuredtext-lint/pull/14 | 18:17 |
| harlowja | ^ that was a fun one | 18:17 |
| harlowja | ^ dive into sphinx land | 18:17 |
| harlowja | lol | 18:17 |
| harlowja | lol https://github.com/twolfson/restructuredtext-lint/pull/14#issuecomment-91770812 | 18:18 |
| harlowja | 'I am still diving down...' | 18:18 |
| harlowja | haha | 18:18 |
| * harlowja hasn't spent a lot of time on doing much to doc8 in a while, but i welcome anyone to help ;) | 18:18 | |
| dhellmann | I've added a list of a few of the standard doc features to each project in the etherpad so we can check them off as we do them (or discover that they are done) | 18:40 |
| harlowja | cool | 18:40 |
| dims__ | dhellmann: ++ | 18:41 |
| bknudson1 | dhellmann: with https://review.openstack.org/#/c/227448/ I get "/opt/stack/oslo.log/doc/source/configfiles/index.rst:5: WARNING: unknown document: opts" | 18:42 |
| *** cdelatte has quit IRC | 18:48 | |
| bknudson1 | (I update the review) | 19:03 |
| dhellmann | bknudson1: looks like I forgot to add a file to that patchset | 19:15 |
| bknudson1 | opts is in the parent directory | 19:15 |
| dhellmann | oh, hmm | 19:16 |
| bknudson1 | so use ../opts | 19:19 |
| dhellmann | bknudson1: fixed | 19:22 |
| bknudson1 | I tried it and it built clean for me. | 19:23 |
| dhellmann | harlowja: I don't understand your comment on https://review.openstack.org/#/c/227447/1 | 19:34 |
| harlowja | dhellmann oh, probably my fault | 19:35 |
| harlowja | i think the main complaint was thats oslo.log right? | 19:35 |
| harlowja | 'underlying messaging system.' in oslo.log? | 19:35 |
| harlowja | 'underlying logging system.' ? | 19:35 |
| dhellmann | ah! | 19:35 |
| dhellmann | yeah, ok | 19:35 |
| harlowja | :) | 19:35 |
| harlowja | thats all | 19:36 |
| dhellmann | harlowja: looks like we're both working on oslo.versionedobjects :-) | 20:11 |
| harlowja | :-P | 20:11 |
| bknudson1 | I get a lot of errors when building oslotest. | 20:11 |
| harlowja | i'm done, ha | 20:11 |
| bknudson1 | building docs for oslotest | 20:11 |
| * harlowja opening bug for pbr, it probably should rst-escape (or something) generated changelogs... | 20:12 | |
| harlowja | because not so hard to cause sphinx to blow-up when including it | 20:12 |
| dhellmann | harlowja: yeah, I noticed that, too, good idea | 20:12 |
| dhellmann | I'm not sure how we escape things like that | 20:12 |
| dhellmann | bknudson1: from master, or from one of the proposed changes? | 20:12 |
| bknudson1 | master | 20:13 |
| bknudson1 | I'm wondering if I'm doing something wrong | 20:13 |
| bknudson1 | ImportError: No module named oslo_config | 20:13 |
| dhellmann | bknudson1: no, that was an issue, I've fixed it in one of my patches | 20:13 |
| bknudson1 | the proposed changes probably fix all this. | 20:13 |
| dhellmann | yeah | 20:13 |
| bknudson1 | ok, thanks | 20:14 |
| dhellmann | we should probably put our names on modules when we start working on them to avoid duplicating effort :-) | 20:14 |
| harlowja | https://bugs.launchpad.net/pbr/+bug/1499519 opened | 20:14 |
| openstack | Launchpad bug 1499519 in PBR "Escape changelog RST" [Undecided,New] | 20:14 |
| dhellmann | harlowja: how about abandoning https://review.openstack.org/#/c/227528/1 in favor of https://review.openstack.org/227530 since the latter is the basis for the patch that adds discoverable options to o.vo? | 20:14 |
| harlowja | sure | 20:15 |
| harlowja | the reason for blank changelog was so people running `sphinx-build` wouldn't crap out, but i guess we can just tell people to run `python setup.py build_sphinx` | 20:16 |
| dhellmann | yeah, we only support running it through tox, and tox installs the lib and that causes the changelog to be built | 20:16 |
| harlowja | k | 20:16 |
| harlowja | fair nuff | 20:17 |
| *** haypo has left #openstack-sprint | 20:23 | |
| *** rfolco has quit IRC | 20:52 | |
| dhellmann | https://review.openstack.org/#/q/project:%255Eopenstack/oslo.*+is:open+file:%255Edoc/source/.*,n,z | 20:56 |
| *** bknudson1 has quit IRC | 20:57 | |
| *** rfolco has joined #openstack-sprint | 20:57 | |
| dhellmann | a better query to show only things worth reviewing: https://review.openstack.org/#/q/project:%255Eopenstack/oslo.*+is:open+file:%255Edoc/source/.*+NOT+is:owner,n,z | 20:58 |
| dhellmann | one more time: https://review.openstack.org/#/q/project:%255Eopenstack/oslo.*+is:open+file:%255Edoc/source/.*+NOT+is:owner+NOT+label:Code-Review%253E%253D0%252Cself,n,z | 20:59 |
| *** rfolco has quit IRC | 21:03 | |
| dhellmann | http://bit.ly/oslo-doc-sprint-dashboard | 21:05 |
| dhellmann | ok, folks, I'm going to take off. I'll check back in tomorrow for more reviews and to see if there are any other additions/cleanups I can make | 21:20 |
| harlowja | ok let's see here | 21:27 |
| harlowja | more docs! | 21:27 |
| harlowja | lol | 21:27 |
| *** dims__ has quit IRC | 21:29 | |
| *** dims_ has joined #openstack-sprint | 21:52 | |
| *** bknudson1 has joined #openstack-sprint | 21:59 | |
| harlowja | ok, think we are doing pretty good | 22:22 |
| *** jhesketh has quit IRC | 22:28 | |
| *** jhesketh has joined #openstack-sprint | 22:29 | |
| dims_ | harlowja: ++ | 22:44 |
| harlowja | dims_ let me know what u think about https://review.openstack.org/#/c/227572/ | 22:46 |
| harlowja | that one may be controversial :-P | 22:46 |
| dims_ | not really, we don't use it anymore. so its fair | 22:46 |
| harlowja | k | 22:46 |
| harlowja | fair nuff with me, ha | 22:47 |
| *** dims_ has quit IRC | 23:05 | |
| *** harlowja has quit IRC | 23:56 | |
| *** harlowja has joined #openstack-sprint | 23:57 | |
Generated by irclog2html.py 2.14.0 by Marius Gedminas - find it at mg.pov.lt!