Misc doc updates #1461

cupakromer · 2014-03-28T15:56:10Z

Starting to do a complete review of all the Relish docs. I often find myself using these daily or trying to point users to them. I've created a list of things that need updating / adding. This is the first pass on the core docs fixing mostly minor issues.

Capitalize the first word of scenarios
Use back ticks for inline code and options consistently
Minor grammatical issues
Fix whitespace wraps as viewed on Relish (wrap to a general 80 cols)
Replace describe instances with RSpec.describe
Clean up any remaining instances of should syntax in example specs

cupakromer · 2014-03-28T15:57:03Z

I'm going to try wrapping this up after I get home from work later.

cupakromer · 2014-03-31T01:35:10Z

I think this is ready for merging. Would appreciate a 2nd set of eyes for a sanity check.

JonRowe · 2014-03-31T01:36:27Z

Needs a rebase...

cupakromer · 2014-03-31T01:37:21Z

One note about the whitespace. After doing a last pass to see how things would render on Relish, there are a few cases where what shows up on relish, doesn't match nicely with the 80 col. breaks.

This seems to stem from Relish using a non-fixed width font. Which can apparently have a drastic affect on line lengths in some situations. The only full solution seems to be to remove the custom line breaks and let the paragraphs continue on and force your editor to perform the wrapping.

JonRowe · 2014-03-31T01:38:01Z

features/command_line/README.md

-either pass a `-rrspec/autorun` CLI option when invoking `ruby`, or add
-a `require 'rspec/autorun'` to one or more of your spec files.
+Generally, life is simpler if you just use the `rspec` command. If you must use
+the `ruby` command, however, you'll need to require `"rspec/autorun"`. You can


I know this is historical, but I'm not sure why we need " around rspec/autorun here.

Ah I think that should be: require "rspec/autorun"

cupakromer · 2014-03-31T02:30:37Z

Change made and rebased against master.

JonRowe · 2014-03-31T03:25:07Z

features/command_line/README.md

-either pass a `-rrspec/autorun` CLI option when invoking `ruby`, or add
-a `require 'rspec/autorun'` to one or more of your spec files.
+Generally, life is simpler if you just use the `rspec` command. If you must use
+the `ruby` command, however, you'll need to `require "rspec/autorun"`. You can


the original phrasing was correct here, (require rspec/autorun) as the mechanism of requiring is specified later.

JonRowe · 2014-03-31T04:17:30Z

Good stuff so far, left some feedback, my major nitpick is at the moment there's plenty of code in Feature/Scenario headings not backticked. (I only commented on a few); I know it doesn't highlight properly but we're currently inconsistent about it and feel we should go full backtick. Developers will mostly know what we mean by them.

myronmarston · 2014-03-31T17:42:11Z

@cupakromer -- thanks for tackling this! It'd be good to add some configuration that enforces certain things about the code in the scenario examples, such as RSpec.describe, the expect syntax, etc. We've done this for rspec-expectations and the same thing should work here:

https://github.com/rspec/rspec-expectations/blob/master/features/support/disallow_certain_apis.rb

cupakromer · 2014-03-31T19:02:34Z

I'll make another pass after work to take care of the backticks for code in the feature and scenario names. I hadn't changed it previously, aside from it not highlighting, as most of the features didn't have them. Only later did I notice a few which did. I'll be sure to standardize on this going forward.

@myronmarston that's really cool. I'll take a crack at it when I get home from work.

cupakromer · 2014-04-02T13:25:29Z

@JonRowe @myronmarston Sorry for the delay, work + house issues have left little free time recently. I put together a small public relish project to demo the different syntax highlighting currently: https://relishapp.com/cupakromer/code-test/docs/testing-code-blocks

You can see the feature I used in this gist: https://gist.github.com/cupakromer/9934026

myronmarston · 2014-04-02T17:34:20Z

Hmmm, looks like you're right. Not sure what I was thinking of. Carry on :).

JonRowe · 2014-04-02T21:24:09Z

So only works if it's inline then..., that's ok, I think I still prefer over 4 spaces...

cupakromer · 2014-04-02T22:24:04Z

@JonRowe we use 4-spaces all over the specs. Just to confirm, we're going to standardize on always using ``` for code blocks in feature descriptions with no indenting?

cupakromer · 2014-04-04T22:15:58Z

Ok finishing this tonight. Made all requested changes. Also, on a happy note, it seems Relish is working out the issues with ```syntax 😄 I'll continue to work with them on that and all the edge cases.

Two things left:

Add configuration to enforce syntax
Rebase against latest master

When viewing in Relish, scenarios read as section titles. General punctuation dictates that section titles should start capitalized.

- Explicitly specify the code block format for Relish - Adjust wording to keep related topics together

Adjust the spec file names to match the description.

Relish supports using triple backticks for code blocks in markdown. This is primarily used in feature descriptions. Relish has a few issues with supporting naming the syntax with triple backticks. We'll standardize on this method while Relish works the remaining issues out.

- Bold notes, warnings, etc. titles - Move convention into a sub-heading

cupakromer · 2014-04-05T05:20:23Z

This should be all done now.

JonRowe · 2014-04-05T11:21:31Z

features/Upgrade.md

@@ -239,7 +239,7 @@ passed to `it_should_behave_like`.

 See [features/example\_groups/shared\_example\_group.feature](http://github.com/rspec/rspec-core/blob/master/features/example_groups/shared_example_group.feature) for more information.

-NOTICE: The including example groups no longer have access to any of the
+**NOTICE:** The including example groups no longer have access to any of the


including or included?

I believe "including" is correct. It seems to be referring to the example group which calls it_behaves_like, which is "including" the shared examples.

How about "An example group including shared examples no longer has access to any of the methods, hooks or state defined inside the shared group." I think it reads slightly better...

🔧 Fixed.

For this file, I didn't actually go over it initially. I just used a regex replace to handle the initial bolding of the notice heading.

JonRowe · 2014-04-06T01:47:59Z

Looking good, few more queries :)

JonRowe · 2014-04-06T01:52:12Z

features/support/require_expect_syntax_in_aruba_specs.rb

+
+    rspec.expose_dsl_globally = false
+
+    rspec.include DisallowOneLinerShould unless ENV['ALLOW_ONELINER_SHOULD']


Why would we want to allow this? (Bearing in mind this is a global setting, not per spec setting)

This is in response to @myronmarston comment about adding standard checks to the code (see: #1461 (comment)).

It's not really global for cucumber specs. This file is added before each feature when it is setup. It is easy to allow the one liner should syntax by tagging the spec with @oneliner-should; rspec-expectations already does this. We can add more tags when necessary too.

Honestly, I don't care very much about enforcing one-liner syntax in rspec-core's cukes because we generally don't use it in rspec-core's cukes except for the ones that are demonstrating the one-liner syntax (where we need to allow both forms anywhere).

rspec-expectations uses the one-liner syntax extensively because it helps us show many usages of each matcher without much extra noise of surrounding code, so we wanted to enforce it there.

But given that you've already set this up, this is great :).

- Remove one-liner `should` and `should_not` - Allow for full override of the customizations

Adjust whitespace for feature description based on space taken by added tags.

cupakromer · 2014-04-08T02:21:02Z

@myronmarston After considering more about the extended checks in the Before block (here 49ca43e) I decided to remove them. The way cucumber loads Ruby files would require a bit of adjustment to make a change I'd be happy with. I'm good with this setup for now.

myronmarston · 2014-04-08T06:16:57Z

Sounds good. I haven't been following this PR in much depth but what I've seen looks good to me and I trust you and @JonRowe so if you think it's ready, merge away.

Misc doc updates

cupakromer mentioned this pull request Mar 28, 2014

Misc doc updates #1447

Closed

2 tasks

JonRowe reviewed Mar 31, 2014
View reviewed changes

cupakromer added 5 commits April 5, 2014 00:46

Standardize capitalization of scenarios.

312f929

When viewing in Relish, scenarios read as section titles. General punctuation dictates that section titles should start capitalized.

Use a more explicit scenario description.

91f4e6b

Update feature description.

f4361d1

Standardize on RSpec.describe over describe.

bf37a20

Surround inline code in back ticks.

eb02899

cupakromer added 11 commits April 5, 2014 00:46

Correct note about x-aliases now skipping.

1a40a32

Make CLI flags explicit across features.

eddecbd

Adjust grammar and HTML rendering.

bbe256f

- Explicitly specify the code block format for Relish - Adjust wording to keep related topics together

Add skip to CLI output --format scenarios.

6f7a193

Add new scenario describing a simple name alias.

f9698b9

Adjust the spec file names to match the description.

Whitespace only update.

d69b368

Replace order feature with basic description.

94f9cb8

Use code backticks in feature and scenario names.

c0a6860

Minor grammatical update.

c468279

- Bold notes, warnings, etc. titles - Move convention into a sub-heading

Standardize on RSpec.describe over describe.

f3a1a8a

JonRowe reviewed Apr 5, 2014
View reviewed changes

JonRowe reviewed Apr 6, 2014
View reviewed changes

cupakromer added 3 commits April 7, 2014 22:17

Update allowed syntax to remove should by default.

49ca43e

- Remove one-liner `should` and `should_not` - Allow for full override of the customizations

Include new doc standards with new feature.

26e41c8

Adjust whitespace for feature description based on space taken by added tags.

A few more minor grammar and formatting updates.

cccb32b

cupakromer added a commit that referenced this pull request Apr 9, 2014

Merge pull request #1461 from rspec/misc-doc-updates

4984a2b

Misc doc updates

cupakromer merged commit 4984a2b into master Apr 9, 2014

cupakromer deleted the misc-doc-updates branch April 10, 2014 02:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Misc doc updates #1461

Misc doc updates #1461

cupakromer commented Mar 28, 2014

cupakromer commented Mar 28, 2014

cupakromer commented Mar 31, 2014

JonRowe commented Mar 31, 2014

cupakromer commented Mar 31, 2014

JonRowe Mar 31, 2014

cupakromer Mar 31, 2014

cupakromer commented Mar 31, 2014

JonRowe Mar 31, 2014

JonRowe commented Mar 31, 2014

myronmarston commented Mar 31, 2014

cupakromer commented Mar 31, 2014

cupakromer commented Apr 2, 2014

myronmarston commented Apr 2, 2014

JonRowe commented Apr 2, 2014

cupakromer commented Apr 2, 2014

cupakromer commented Apr 4, 2014

cupakromer commented Apr 5, 2014

JonRowe Apr 5, 2014

cupakromer Apr 5, 2014

JonRowe Apr 6, 2014

cupakromer Apr 6, 2014

cupakromer Apr 6, 2014

JonRowe commented Apr 6, 2014

JonRowe Apr 6, 2014

cupakromer Apr 6, 2014

myronmarston Apr 6, 2014

cupakromer commented Apr 8, 2014

myronmarston commented Apr 8, 2014


		rspec.expose_dsl_globally = false

		rspec.include DisallowOneLinerShould unless ENV['ALLOW_ONELINER_SHOULD']

Misc doc updates #1461

Misc doc updates #1461

Conversation

cupakromer commented Mar 28, 2014

cupakromer commented Mar 28, 2014

cupakromer commented Mar 31, 2014

JonRowe commented Mar 31, 2014

cupakromer commented Mar 31, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cupakromer commented Mar 31, 2014

Choose a reason for hiding this comment

JonRowe commented Mar 31, 2014

myronmarston commented Mar 31, 2014

cupakromer commented Mar 31, 2014

cupakromer commented Apr 2, 2014

myronmarston commented Apr 2, 2014

JonRowe commented Apr 2, 2014

cupakromer commented Apr 2, 2014

cupakromer commented Apr 4, 2014

cupakromer commented Apr 5, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JonRowe commented Apr 6, 2014

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cupakromer commented Apr 8, 2014

myronmarston commented Apr 8, 2014