`gofmt` examples in README

[jtarchie]

As an open-source maintainer, I know how helpful having valid working examples in the documentation can be. This is an attempt to update the examples to be copy-pasted.

This transformation was part programmatic, part manual editing. I wrote a little Ruby script that took the code example between the triple-backticks, then tried various "fixes".

• add a package name
• replace placeholder ... and ??? with multiline comment fenceposts
• try go fmt

If it could be formatted, I tried to resolve the issue manually until it could, or I decided I could not resolve it for reasons.

This was a quick pass. Not meant to be definitive.

# frozen_string_literal: true

require 'tempfile'

filename = ARGV[0]
contents = File.read(filename)

contents.gsub!(/(?<=```go\n)(.*?)(?=```\n)/mu) do |original_code_block|
  code_block = original_code_block

  unless code_block.match(/^package \w+$/)
    # puts '  🚧 adding default `package books_test`'
    code_block = "package books_test\n#{code_block}"
  end

  filler = /\s+(\.\.\.|\?\?\?)\s+/
  if code_block.match(filler)
    # puts '  🚧 cleaning up filler'
    code_block = code_block.gsub(filler, '/* \1 */')
  end

  file = Tempfile.new(%w[main go])
  file.write(code_block)
  file.close

  skipper = /INVALID|is equivalent to/
  if original_code_block.count("\n") <= 3 || original_code_block.match(skipper)
    # puts '  ✅ valid go'
    original_code_block
  elsif system("gofmt -w #{file.path}")
    # puts '  ✅ valid go'
    File.read(file.path)
  else
    puts code_block
    puts '  🔴 could not format file invalid go'
    original_code_block
  end
end

File.write('errors.md', contents)

[onsi]

hey - I appreciate the time and thought put into this, @jtarchie - but I'm a bit torn. Some thoughts:

• the code in the docs was never intended to be copy-pastable. For one thing... there is no books package, let alone all the types/structs/functions etc. used in the docs. The intent, rather, is to give folks concrete examples to illustrate GInkgo's usage and behavior. A sort of "read this and learn so you can apply it in your own code-base". A more tutorial-like thing could make sense but I don't think it would have the scope of the entire doc-set. Rather it would be constrained to more of a "getting started" scope.

• I get that package books_test would appear in actual go code... but so would a bunch of import statements (which would be needed for it to be truly copy-pastable)... But that would just be noise that obscures from the core thing being presented - which is the code. Given that I'm not sure adding package books_test everywhere is adding much.

• I actually intentionally avoided go fmting the code. Precisely because that introduces a lot of additional horizontal whitepsace. This is fine when looking at the docs on a laptop/desktop/tablet, but when looking at the docs on a mobile device one quickly runs out of horizontal space. So rather than go fmt (which introduces a tab character, I believe) I went with two spaces.

But go fmting the examples would be super useful. And I think we can solve for the horizontal space issue via css. So, if you're up for rerunning your script but without the package books_test but with the go fmt stuff (and update the CSS if you're up for it) that would be super valuable.

Thoughts?

[jtarchie]

Thanks for the feedback, not ignoring, just on vacation. 😄

I will explore your proposal here. Any leads on where the CSS I need to edit would be?

[onsi]

No worries, obviously! Hope vacation's going/gone well :)

I think it probably goes here somewhere:

https://github.com/onsi/ginkgo/blob/74bbd6552ca29d47cf6c828aac38d42fbd912bd9/docs/css/layout.css#L62-L80