Document config options #723
Conversation
|
These look great to me. Awesome work 馃憤 |
|
I skimmed over these, and it's all positive. @charlietanksley, should I review more in depth and merge these if everything is OK? |
|
@alinderman not yet. I'd like to document the remaining options. I just wanted to make sure I was on the right track before finishing. I'll get to that this week and let you know when it is done. Thanks. @soulcutter thanks! |
|
Sorry, for the typo in your name, @alindeman! |
Since `order` and `seed` are pretty tightly coupled, it seems like these should be documented together. But the only way I can think of to write a feature for seed would be to try and run a spec, capture the seed, then insert that into a config block. But that seems way too complicated to be informative as documentation. So after consulting with @alindeman I opted to just link to where these features are documented for the command line options.
|
The only part of rspec/rspec-rails#422 left to do is put a link to the Rdoc on https://www.relishapp.com/rspec. I couldn't find that home page so I didn't know how to add that, but I'm happy to add it if you'll point me in the right direction. And let me know if there are any parts of any of these that need to be changed for any reason. Or if I should squash them to one big commit. 馃槃 |
|
RDoc is on http://rubydoc.info (http://relishapp.com supports Cucumber features). These docs will show up automatically once this is merged under http://rubydoc.info/github/rspec/rspec-core and then under http://rubydoc.info/gems/rspec-core when we do a release. |
|
Awesome. I thought in the issue over on rspec/rails one of the suggestions was to put a link to rdoc from relishapp. Sounds like that is unnecessary, though. :) |
|
@charlietanksley, is this ready to go? We're discussing what |
|
@alindeman, yes, it's good to go, then. |
| end | ||
| """ | ||
| When I run `rspec spec/example_spec.rb` | ||
| Then the examples should all pass |
There was a problem hiding this comment.
I'm glad we're getting some docs in place for the DRb stuff, but I'm not sure that these scenarios have much documentation value...they don't demonstrate what the DRb options do; they just show that when you set them, the configuration object stores the values you set.
This is going to sound funny given that I'm the lead maintainer for rspec now...but I'm not even sure how to use the DRb options (I've never used the options). I know spork uses it but it'd be nice to document how to use it w/o spork. Not sure how feasible it is to demonstrate that with a scenario here, but if it was feasible, it would be a huge improvement, I think. Or, even if it's not feasible, maybe some additional text at the top explaining why you would want to use the options and how you would use it?
There was a problem hiding this comment.
I know spork uses it but it'd be nice to document how to use it w/o spork.
Is there a common use case outside of tools like spork? I also am not too familiar with them beyond that, if so.
There was a problem hiding this comment.
I agree that this doesn't provide tons of documentation value. @myronmarston, you're right that it merely shows that the DRb option can be turned on and that you can set the port (and that there is no port set by default).
I haven't the foggiest clue how to document this any further. If you guys don't know how it is used, I sure don't! So I'd vote that if you think that this documentation adds nothing, we just scrap it. I think the other documentation here is helpful, so I'd like to see it added even if we drop the DRb documentation. Do feel free to cut these features. Whatever you see fit to do.
There was a problem hiding this comment.
We'll definitely merge the rest of the documentation stuff you wrote up (it's really great) but I'm hoping @dchelimsky can weigh in on the DRb options first. @dchelimsky -- if you get the chance, it'd be nice to get a description of how to use these options, if for no other reason than to provide a "here's how to use them guide" for me so if/when I refactor any code involving the DRb stuff I can verify I haven't broken it. If it's feasible to turn that into a cuke we can do that as well.
There was a problem hiding this comment.
Cool. If I know how to document the DRb options I'm happy to do it. I'll watch for updates :)
There was a problem hiding this comment.
Basically, you add --drbto the command line to run via spork. That's it. AKAIK, drb is only ever used w/ spork and drb_port is never used (well, it's used internally, but never by a user).
There was a problem hiding this comment.
I knew spork was the primary library that relies on rspec's DRb support. Spork's usage of this should be relying upon public APIs that another bit of code or library could use as well, though, right? Can we document how the rspec DRb protocol works (as a standalone thing, without referencing spork as the only way to use it?). I'm thinking something along the lines of "start rspec with the drb option, then send it commands by doing XYZ".
Maybe it's not possible to distill how spork uses rspec down into something easily documentable, but it would be nice to do so.
|
@charlietanksley Thanks for your hard work on this, and sorry for taking so long to merge this! I just merged it finally. |
This pull request isn't yet complete. There are still a handful of options in rspec-core to document like this, and then I need to document the ones in rspec-rails. This pull request is actually the first part of trying to close rspec/rspec-rails#422.
I'm submitting this early just to make sure I'm on the right track with my approach. Let me know if I need to do anything differently, and I'll let you know when the pull request is complete! 馃樃