Reorganized sample code and began rewriting the User Guide, with changes to affected documents

[mslinn]

This is a huge PR. It arose from my attempts to run the code examples in the User Guide. Along the way I realized that most of them in fact did not run, so I raised #384. As I mentioned in the #384 comments, the code examples needed to be reorganized so they could be run.

This PR:

• Adds material to the User Guide (should be checked for accuracy)
• Moves code examples to the new top-level examples directory
• Adjusts every reference to the moved code examples
• Adds TODO and FIXME comments in broken code examples (remember, these examples were previously broken).
• All tests pass
• Commits were squashed

There is no easy way to make these changes, and I think it makes sense to do all the work in one PR instead of many repetitive and painful PRs. I suggest that the embedded FIXME and TODO comments remain, that the PR be merged, and then follow-on PRs be created to address related FIXME and TODO issues.

[krasserm]

Thank you for your work on re-structuring the examples. I appreciate your contributions but the pull request is by far too large. IMO it can easily be broken into several smaller ones, for example:

• re-organize the existing examples under a single root. The single root shall remain an Eventuate sub-module not a completely isolated sbt project. If you really want to have a completely isolated example (demonstrating all the necessary sbt and dependency settings) move it to a separate repository.

• change the examples to become executable from the sbt command line without affecting the content in the documentation. The only required change in the documentation might be a hint where the runnable examples are located and how to run them.

• revision the user guide and other parts of the documentation where you think wording or content can be improved.

• ...

This is only a suggestion how work can be split into several smaller pull requests. I’m happy to discuss alternatives. Also, after a quick walk through your changes, I have some general notes (in random order):

• The organization is the example sbt files is com.micronautics. This should be com.rbmhtechnology.
• There are several .travis.yml files in the examples. I don’t see that they are necessary.
• The build.sbt files are highly redundant/repetitive. Try to avoid that, otherwise, it’s going to be a maintainence hell when dependencies and/or general settings change.
• Please do not just comment out lines in build.sbt or application.conf. Remove them if they are not needed.
• Please use meaningful commit messages. The current one (when expanded) is confusing.
• Most of the changes in spark.rst are new linebreaks. Either follow that style in all .rst files or none of them. I’d prefer the latter (i.e. the current state).
• There are some .pyc file checked in. Please remove them.
• Do not use TODO or FIXME in files to track work to be done in the future. Use the issue tracker instead.
• Do you insist on having ... and Mike Slinn in the copyright headers? I don’t know if this is in conflict with the CLA. Have to check that /cc @purthaler.

I'll give more detailed feedback to the smaller pull requests.

[mslinn]

Martin, Most of your items are acceptable, but I cannot agree to two of them. I thought we had agreement on these items before I started. Code examples and documentation are written for the benefit of the reader, not the writer. 1. It is important for the reader to be able to try code examples without getting tangled up in the library code base and documentation publishing system. It is possible and even preferable for the code examples to be in in separate GitHub projects. Perhaps that might be done at a later time, however for now I have merely put them under the examples/ directory. From what I now know of Sphinx, separating the examples from the library code is possible, and a case might be made to also separate all of the Sphinx-related content from the code as well. I am not advocating moving Sphinx at this time, but I can see the benefits of doing so. One benefit is that the documentation staging would be independent of the library releases. 2. It is a false economy to apply DRY to code examples. Instead, the examples should correspond to documentation that builds the user's understanding from section to section. Commented out entries in build.sbt tell the user two important things: (1) these modules exist, and (2) these modules are not required for the given code example. Putting all code examples together into one project makes it harder for users to learn what each module does, and for them to understand which files are relevant for the topic being taught. Sharing a build system between the library code and the code examples makes it really hard for users to run the code examples. The code examples that we provide from ScalaCourses.com are provided via several distinct SBT projects for these same reasons. We use a simple bash script to update dependencies. It is possible to perform the update in various other ways, for example the publish command could kick off a search-and-replace that ensures code examples are built and tested with the correct dependency versions. Thank you, Mike

[krasserm]

It is important that the examples use the very same settings as Eventuate itself for compilation and running. Otherwise the quality of the examples cannot be guaranteed. Requiring discipline from developers to maintain that at several locations has proven to be error-prone in the past, that's why I don't want to violate DRY in the Eventuate build.

If you want to demonstrate how to setup a build.sbt file from scratch, either create a separate example repository or provide a template for Lightbend Activator, Giter8 or whatever. For example, @volkerstampa created a very useful activator template for the Eventuate example application.

It would be great to have several templates for different use cases e.g. single location app, multi-location app, CmRDT app, ... from which you can create a running project from the command line. Ideally, the created project contains sample code with running unit and integration tests.