Documentation website

[kddnewton]

The current project documentation consists of using RDoc to publish to GitHub pages and the README. These are fine resources, but don't really tell the whole story. Also, I do not understand how to cannot navigate the RDoc pages, and I'm the author of the gem.

Instead, we should build a full-on documentation website. This should include all of the information that we already have, plus a lot of stuff that we don't have, like:

• Tutorials/example projects. For example:
  • A small Ruby gem that integrates Syntax Tree formatting into its Rakefile.
  • A Ruby project that uses the mutation feature to ship a codemod for a breaking API change.
  • A project that uses the DSL feature to build valid Ruby code on the fly.
  • A project that stores searches for quick onboarding.
• Integrates ruby-syntax-tree.github.io
• Groups nodes together instead of having a flat map of them, and has nice, accessible examples of each node. (We actually already have this in source, but it is very difficult to find the right nodes because they're all listed at the same level.)

[faraazahmad]

I would like to help out on this. Personally I've never been a fan of RDoc and I think RuboCop's docs do a much better job https://www.rubydoc.info/gems/rubocop

[faraazahmad]

@kddnewton I really like how haml.info has their website and docs arranged. They do a good job IMO at many of the core points you mentioned:

• Tutorial: https://haml.info/tutorial.html
• Website feels connected to the overall help/docs for the project
• YARD docs API Refernece has classes grouped together in an easily navigable way (like the RuboCop::AST docs)

Looking forward to your feedback on this

[kddnewton]

Yeah I like that too!

The thing I'd like to have is to have the https://ruby-syntax-tree.github.io/ functionality embedded into the docs as well, so that folks can play around with it live.

[faraazahmad]

I like this approach! However to do this we'd need to add a dropdown or something in the live preview to select what code we want in the editor, sort of like the Go Playground

Or is there a simpler way to do this?

[kddnewton]

Yeah I think something like that would work nicely. But I'd also like it have a file viewer with the file contents, because it would be nice to allow the user to run format/mutate/index/ctags on a given source file and see the output.