Earlier  
Later
New Search
Posted Nick Remark
#openstack-sdks - 2019-10-28
16:41:19 efried sorry, "do that" what?
16:41:24 dtroyer move all of their docs
16:41:37 dtroyer python-openstackclient as functioanlity and docs for that in one place
16:41:39 efried well, the docs at $plugin are a separate thing.
16:41:54 dtroyer and openstackclient is the integration point, not python-openstackclient
16:42:40 dtroyer this is such a mess because that transition was not completed and isn't a high enough priority (until now) for anyone to spend time on it
16:44:10 dtroyer this is life in a project that nobody really wants to pay for… "clients are not important" — a (former) OSF Platinum Board Member
16:44:49 efried okay, it's not a super high priority, I just came across it because I was trying to get at some plugin docs and couldn't find them in the first few obvious places I looked. What exists now is a dramatic improvement, but it's brittle.
16:45:06 efried Before, $plugin could merge a broken option help and nobody would be the wiser
16:45:18 efried like, literally nobody, because those weren't being used *anywhere* afaict.
16:45:27 efried Not even sure if they were being used to build the CLI helps. Maybe they were...
16:45:41 efried but those obv don't have the same rules as the sphinx-built docs.
16:46:15 efried anyway, now if $plugin merges and releases a bogus option help, python-openstackclient will start to fail its doc build.
16:46:29 efried so it would be nice to prevent that rather than having to go fix it after the fact.
16:46:48 efried esp because the rate of change in python-openstackclient is so low, it could be ages before anyone even notices the breakage.
16:47:15 dtroyer again, this is why I did not want to be in the integration business
16:47:46 efried understood
16:47:48 dtroyer at least not in the python-openstackclient repo
16:48:16 efried can you just bear with me a little bit longer and help me understand what the ideal utopian future state of this openstackclient repo would be?
16:49:08 efried and then I'll just take the ball and run it wherever I think will get us closer, if probably not actually all the way there.
16:50:49 dtroyer sure: anything and everything that should be handled across all (self-identified) plugins and OSC itself should happen there… docs, co-installability testing, whatever. Even registering their existence. Definition of the jobs so plugins (and OSC) can run the jobs to do the checking as those projects decide they care. This is meant to be opt-in, as I don't enforce the OSC command structure standards on plugins (I lost that argument too), we'll t
16:53:58 openstackgerrit Riccardo Pittau proposed openstack/openstacksdk master: Add reset_interfaces argument to patch_node https://review.opendev.org/689414
17:06:04 efried dtroyer: before I go asking the docs folks, any idea why openstackclient docs aren't being published? I see a doc/ dir with appropriate requirements, config, and an index.rst; and the .zuul.yaml lists the build-openstack-docs-pti template
17:07:38 dtroyer efried: it may have never been set up, that repo wasn't really used until I released OSC 4 a couple of months ago
17:37:39 openstackgerrit Eric Fried proposed openstack/openstackclient master: Update doc index links (for storyboard etc) https://review.opendev.org/691728
17:38:35 efried dtroyer: I'm gonna see if this builds docs at least in zuul. If it does, I think I'm going to copy all (or most?) of the docs from python-openstackclient into it. Then I can beef up that zuul job to build docs as well as do that dup check. Then I can start spraying that job into all the plugin projects.
17:39:17 efried even if the docs never get published, that job running in zuul will allow us to gate and detect future option help breakages.
17:40:08 dtroyer efried: ok, thanks for spending time on this
17:40:17 efried eventually if the docs do get published, we can stuff redirects in python-openstackclient, but we would probably still want *some* of the docs available there, so I'm not going to get real excited about that yet. Problem for future-us.
17:40:29 efried yahyoubetcha.
17:43:42 efried ...seems to have worked fine
17:50:56 efried okay, it's not publishing because it's using the build-...-pti job, not the publish-...-pti job.
17:50:56 efried ...which actually could be useful for our purposes here. Means I could make the docs build gate plugin projects without actually having to worry about whether the docs are pretty or correct.
17:51:29 efried dtroyer: that said, if you *do* want to start publishing those, it would be trivial at this point. Do you want me to pull that trigger?
18:29:52 openstackgerrit Merged openstack/openstacksdk master: Switch to Ussuri jobs https://review.opendev.org/691158
19:26:31 dtroyer efried: I'm not sure I want to publish docs outside of where they are maintained. ie, a single consolidated doc requires someone to curate it and I'm not signing up for that. I understand the ux sux but adding anything beyond pointers to the individual pieces eventually makes a worse experience when it gets stale
19:27:02 dtroyer I've always found bad docs more frustrating than no docs FWIW
19:27:05 efried dtroyer: that's not really the question at the moment.
19:27:47 dtroyer than I'm misunderstanding it
19:27:48 efried Maybe I misunderstood, but I thought the eventual goal was to maintain the osc docs in the openstackclient project, not python-openstackclient.
19:28:06 efried this would be a step in that direction, though not getting us all the way there yet.
19:28:18 efried do you mean maintaining docs outside of where the corresponding code is maintained?
19:28:27 dtroyer no, the OSC docs belong with the code, just like the plugin docs
19:28:58 dtroyer a unified guide of some sort would be great, but that's what we don't have the capacity to do, very similar to the overall docs efforts
19:31:53 efried okay, so here's my current strategy:
19:31:53 efried - Copy the python-openstackclient docs to the openstackclient project. Keep the build-...-pti, don't publish yet.
19:31:53 efried - Beef up the openstackclient-plugin-jobs template to include building those docs ^.
19:31:53 efried - Make sure all the plugin projects gate on openstack-plugin-jobs. This prevents them from merging patches with broken option helps.
19:32:37 dtroyer I don't want to move docs from python-openstackclient to openstackclient
19:33:06 dtroyer unless they are bits talking about the entire collection of things. leave the individual command stuff with the commands
19:33:46 efried Right.
19:33:47 efried The next (future, I'm not planning on doing this any time soon) steps would be:
19:33:47 efried - Scrub the docs in both projects to keep the appropriate ones in the appropriate project. Add redirects from any python-openstackclient ones we remove. (No redirects from openstackclient are necessary because never published.)
19:33:47 efried - Start publishing openstackclient docs.
19:34:17 efried but for now the easiest thing to achieve the goal (which is being able to prevent broken plugin docs from merging) is to do a full copy.
19:34:49 dtroyer can you do it the same way you do the plugins today? I don't think you are planning to copy those docs too, right?
19:35:17 efried That's exactly what I'm doing, albeit with a slightly bigger hammer.
19:35:59 dtroyer ok, when you say copy, I read check-in, is that incorrect?
19:35:59 efried I could pick and choose which docs to copy over, to achieve the sole goal of preventing the breakages, but that would be harder and the resulting docs would be not necessarily cohesive (not that that really matters at this stage).
19:36:30 efried I meancp -r python-openstackclient/doc/source openstackclient/doc/source
19:36:36 efried git add -A
19:36:38 efried git commit
19:36:49 dtroyer you are doing that with all plugins too?
19:37:26 efried the plugin "docs" that are part of python-openstackclient are just a couple dozen pages with one autoprogram-cliff line in them. That automatically sucks in the docs from the respective projects.
19:37:37 efried so those are coming along, in the same referential-y way.
19:38:14 efried example:
19:38:14 efried this https://opendev.org/openstack/python-openstackclient/raw/branch/master/doc/source/cli/plugin-commands/sahara.rst
19:38:14 efried produces this https://docs.openstack.org/python-openstackclient/latest/cli/plugin-commands/sahara.html
19:40:40 dtroyer it seems like way overkill to just copy it all only to filter it someday. having two copies out there _will_ confuse someone even if we don't publish it
19:41:11 dtroyer if you fix zuul for me I'll copy the structure over tonight…
19:42:32 efried "the structure"?
19:42:51 efried and "fix zuul"?
19:44:48 efried If you strongly prefer not to have two copies, I can make a hacked-up page that's hidden from view that just does the auto doc generation stuff. It would still build (and thus break if plugins f'ed up their opt helps) but we would have no duplication.
19:57:59 openstackgerrit Merged openstack/openstacksdk master: CI: add ironic-python-agent-builder to the ironic job https://review.opendev.org/691630
20:36:25 openstackgerrit Eric Fried proposed openstack/python-openstackclient master: Use autoprogram-cliff for remaining plugin docs https://review.opendev.org/690387
20:37:04 openstackgerrit Eric Fried proposed openstack/openstackclient master: Copy in python-openstackclient docs https://review.opendev.org/691750
20:37:04 openstackgerrit Eric Fried proposed openstack/openstackclient master: Add docs build to openstackclient-plugin-jobs template https://review.opendev.org/691751
20:46:16 openstackgerrit Eric Fried proposed openstack/openstackclient master: Copy in python-openstackclient docs https://review.opendev.org/691750
20:46:16 openstackgerrit Eric Fried proposed openstack/openstackclient master: Add docs build to openstackclient-plugin-jobs template https://review.opendev.org/691751
21:00:22 efried dtroyer: Update:
21:00:22 efried - those reqs bumps merged, so this patch ought to be ready for review (python-openstackclient, autodocs the last five plugins): https://review.opendev.org/#/c/690387/
21:00:22 efried - I pushed up the openstackclient series above, which
21:00:22 efried - updates the index https://review.opendev.org/691728
21:00:22 efried - copies over all the docs from python-openstackclient https://review.opendev.org/691750
21:00:23 efried - tries to make the openstack-plugin-jobs template build docs (but I did it way wrong, need to rework) https://review.opendev.org/691751
21:02:08 efried oh, and trying to do autoprogram-cliff:: openstack doesn't work. It needs to match the entry point exactly.
21:02:25 efried the granularity is accomplished via that :command: syntax - but is optional.
22:31:24 openstackgerrit Eric Fried proposed openstack/python-openstackclient master: WIP: neutron: autogenerate docs https://review.opendev.org/691767
22:31:46 efried dtroyer: FYI, I'm at least starting to go through and replace hardcoded content with autogen ^
#openstack-sdks - 2019-10-29
10:16:47 openstackgerrit Riccardo Pittau proposed openstack/openstacksdk master: Add reset_interfaces argument to patch_node https://review.opendev.org/689414
10:18:10 openstackgerrit Riccardo Pittau proposed openstack/openstacksdk master: Add reset_interfaces argument to patch_node https://review.opendev.org/689414
10:54:40 openstackgerrit Dirk Mueller proposed openstack/cliff master: Revert "Pin cmd2 back to <0.9 on all versions" https://review.opendev.org/691841
11:55:11 openstackgerrit Merged openstack/openstacksdk master: Increase dogpile version for Py3.7 compatibility https://review.opendev.org/691680
13:57:35 openstackgerrit Eric Fried proposed openstack/python-openstackclient master: Remove redundant OpenStackShell.prepare_to_run_command https://review.opendev.org/691865
13:57:51 efried dtroyer, mordred: Easy one ^
14:22:57 dtroyer efried: not necessarily easy, there were reasons that exists, and at the moment I don't recall if all of those reasons are gone yet. They should be but I wouldn't bet dinner on it right now
14:23:21 efried dtroyer: I linked the superclass impl in there
14:23:58 efried At least from what I can tell, it's doing the same thing. And you said yourself (in the TODO) that it could be removed after 1.4.0 :P
14:23:58 efried But anyway, this is why we have reviews...
14:24:17 dtroyer Then it should be good, but consider the author

Earlier   Later