Site for Eventsourced

[ahjohannessen]

It would be awesome to have a small site for Eventsourced that follows same "mantra" as the one Spray has.

Inspiration for build stuff:

• https://github.com/typesafehub/doc-template
• https://github.com/spray/spray/tree/master/project

[ahjohannessen]

@krasserm

What do you prefer, a fully-fledged site a la spray or something similar to that of Akka, sbt and Slick docs site? One difference is that the Spray approach requires hosting whereas the latter can be on github.

[krasserm]

Using the same doc templates as Akka and sbt are using would be great. Would that mean we also have to rewrite the user guide in rst format?

[ahjohannessen]

I am not entirely sure, but Pandoc seems to be fit for the conversion job. If not, I could happily do that. But again, this depends on your preferences.

[krasserm]

Ah, didn't know Pandoc. Sure, let's give it a try and see what happens. If the conversion is good, we still could have the mastercopies in markdown and publish the rst result. But I'm also open to work with rst only ... once I learned it :)

[ahjohannessen]

@krasserm

I was thinking that publishing to gh-pages by way of https://github.com/sbt/sbt-ghpages could be a nice thing to have. I just need to figure if travis allows for installing sphinx via its yaml file (not entirely sure, but almost certain that is possible)

I have been a bit busy with work stuff and such, but will start work on this soon :)

[krasserm]

@ahjohannessen

no rush, take as much time as you need :)

Using sbt-ghpages in combination with sbt-site sounds reasonable to me. Even if we can't get it running on Travis, we can also install it on the Linux server I'm running locally. This server is running Jenkins and currently doing the following tasks:

• It builds and tests eventsourced master and then publishes SNAPSHOT artifacts to http://repo.eligotech.com/nexus/content/repositories/eligosource-snapshots/. This is in addition to the Travis build. The Travis build was more intended for contributors to see if their pull requests break the build. Was very helpful so far.
• It also generates and aggregates Scaladocs from all modules using the Unidoc sbt settings borrowed from the Akka project. The Scaladocs are generated to target/unidoc by running sbt unidoc.
• It then builds eventsourced-example master using the previously published eventsourced artifacts.
• Finally, it starts another build that publishes the generated and aggregated Scaladocs. It is a separate Jenkins build working on the eventsourced gh-pages branch. It is doing more or less what is described in this blog post. The aggregated Scaladocs are committed and pushed to the api/snapshot directory on the gh-pages branch. I'm completely open to switching to a sbt-ghpages and sbt-site based approach here.

Whatever we're going to change, I'd like to keep the api/snapshotdirectory, if possible. Some external links are already pointing to it. From what I've seen so far, it doesn't seem to conflict with other stuff we want to generate.

Furthermore, I want to avoid storing any credentials (private deploy keys, maven repo passwords, ...) on the Travis CI infrastructure unless they have some convincing means to protect them ...

WDYT?

... and thanks for keeping working on this task. Highly appreciate it.

[krasserm]

Furthermore, I want to avoid storing any credentials (private deploy keys, maven repo passwords, ...) on the Travis CI infrastructure unless they have some convincing means to protect them ...

I see http://about.travis-ci.org/docs/user/travis-pro/#How-can-I-encrypt-files-that-include-sensitive-data%3F as an option to encrypt credentials.

[krasserm]

@ahjohannessen do you still plan to work on that?

[ahjohannessen]

@krasserm I think your comments above are sound:

• Nice that you are so open and welcoming wrt build server etc with respect to getting stuff to work :)
• api/snapshotdirectory is not touched. Agreed.
• Special credentials. Agreed.

Unfortunately, I have been swamped with work around using akka/eventsourced for our backend. So, with that in mind I still have high interested in Eventsourced, reason for being so quiet is because of priorities and learning new stuff about this new ecosystem (coming from .net) .

I still plan to work on this, I just need to get my air back :)

[krasserm]

No rush and thanks for your ongoing interest :)

[ahjohannessen]

@krasserm Finally got around to start working on this :)

[ironfish]

Exciting. Can't wait to see it.

[krasserm]

Woohoo!

[ahjohannessen]

Just a little heads up.

I have managed to setup the necessary bits for:

• Necessary conversion tool to convert markdown to rst (via pandoc)
• Sphinx build support.
• Akka based theme, e.g. like their docs site.

Now I am struggling a bit with some minor conversion issues, but I am investigating this.

Essentially, I have created a project called "eventsourced-site" that has a sphinx folder with stuff like extensions, pygments and theme and then a rst folder with the documentation.

So, as soon one does a "make-site" from top-level project (eventsourced) in sbt it generates a folder under es-site/target/ that contains the generated html. It is also possible to do a preview-site in sbt that opens the site in your browser.

[krasserm]

@ahjohannessen this sounds really good, thanks for the update. Is the markdown -> rst conversion good enough so that we can continue writing docs in markdown or should we switch to rst directly? What I like with markdown is that github does the rendering automatically.

[ironfish]

+1 for markdown.

On Fri, Apr 12, 2013 at 1:33 AM, Martin Krasser notifications@github.comwrote:

@ahjohannessen https://github.com/ahjohannessen this sounds really good, thanks for the update. Is the markdown -> rst conversion good enough so that we can continue writing docs in markdown or should we switch to rst directly? What I like with markdown is that github does the rendering automatically.

— Reply to this email directly or view it on GitHubhttps://github.com/eligosource/eventsourced/issues/59#issuecomment-16276660 .

Duncan K. DeVore <><

[ahjohannessen]

@krasserm Longterm, it probably makes sense to switch to rst directly if we are going to have the docs spread across different subfolders (like akka etc. do) and if pandoc cannot convert without intervention.

I understand your point with markdown being rendered automatically. However, there are a few tools available for editing and rendering automatically in rst:

http://stackoverflow.com/questions/2746692/restructuredtext-tool-support

I wonder how the Akka, Spray and SBT guys approach this and what kind of rst editor they use.

This seems to be a nice, yet simple, online editor for rst: http://rst.ninjs.org

[krasserm]

@ahjohannessen thanks for the rst tooling links. They make it clear that the tooling support for rst is pretty strong. For processing markdown docs spread across different folders we could also consider using http://software.clapper.org/sbt-lwm/ but I'm not sure if this plugin is still actively developed and maintained. Compared to the rst tooling chain this plugin seems to be more limited, though. But what interests me most: could you automatically convert the existing markdown files to rst or was there manual intervention necessary?

@ddevore what are your main reasons for preferring markdown? Mine are primarily that I'm familiar with it in addition to the reason mentioned my previous comment. But there are also things that I'm missing with markdown (at least I'm not aware of their existence):

What I'm missing with markdown is that code cannot be included/inlined into docs based on tags/metadata in the scala source files which would be very helpful for the examples. This could avoid stale code in the docs should the example code change e.g. during a refactoring. @ahjohannessen is this possible with rst and its tooling chain?

[ahjohannessen]

@krasserm I think that I can get most of it to work automatically with some minor corrections in the markdown. This is mainly centered around using ticks in some links, the html build reference and some spaces after code examples. Even though much is transformed for free, some corrections are probably needed to get it to look nice.

@krasserm I believe it is possible to embed code examples directly, Slick does this, not sure about Akka and Spray though. My general impression is that rst is more powerful for automating things. I have noticed that some of the docs from other Scala projects take advantage of automation, e.g. inject version number, embed code and so on.

@ddevore As far as I can tell, rst is as powerful as markdown, but the convenience with github editor is nice. However, IMO, going with sphinx it becomes possible to do some interesting things, e.g. embed code in docs and ensure that examples break the doc builds if the API changes and similar. We get docs a la Akka style :)

[ironfish]

@krasserm Mine is the same as yours. I'm familiar w/ Markdown and have been a big fan of it for some time. I appreciate its simplicity. On a side note, I know the author of sbt-lwm as he (Brian Clapper) is a friend of mine. I'll reach out to him and see if he is/intends to maintain the library.

@ahjohannessen We should use the best tool for the job, and if that's RST then it makes sense to use it. I'm not familiar w/ it but it sounds pretty powerful. I know some guys at Typesafe (previous co-workers) and reached out to them to see what tools they use. I'll let you know what I find out.

[ironfish]

My bad - clicked the wrong button ;-(

[ironfish]

@ahjohannessen From looking at the Akka Github site, it does indeed look like they are using sphinx and RST.

@krasserm As for editor's, it looks like there is a lot of stuff out there. In particular I found two plugins for sublime:

• RST Preview
• RST Completion

[krasserm]

On a side note, I know the author of sbt-lwm as he (Brian Clapper) is a friend of mine. I'll reach out to him and see if he is/intends to maintain the library.

Great, thanks.

We should use the best tool for the job, and if that's RST then it makes sense to use it.

+1

As for editor's, it looks like there is a lot of stuff out there

I'll also try http://plugins.jetbrains.com/plugin?pr=idea&pluginId=7124

I think that I can get most of it to work automatically with some minor corrections in the markdown

If this allows us to have a fully automated markdown -> rst conversion, I think this is a reasonable short-term solution. Should we succeed to include snippets from .scala files and this is possible with rst only, we should consider switching to rst in a second step. But let's also wait for Brian Clapper's response.

[ironfish]

@krasserm Spoke to Brian and he does stay on top of it recompiling when necessary, etc.

[krasserm]

@ddevore good to know, thanks.

[ironfish]

@krasserm @ahjohannessen Just found out from Typsafe the Akka team (Viktor) that they use Jekyll. Here's the Jekyll Github link.

[ahjohannessen]

That confuses me a bit, because I cannot find traces of Jekyll in the akka source. All their docs are in rst, take a look here: https://github.com/akka/akka/tree/master/akka-docs/rst and here: https://github.com/akka/akka/blob/master/project/AkkaBuild.scala#L471

[ahjohannessen]

If this allows us to have a fully automated markdown -> rst conversion, I think this is a reasonable short-term solution.

I will look more into this tonight :)

[ironfish]

@ahjohannessen yeah I see what your saying about Jekyll. Not sure, just the feedback I got from them. I say lets use whatever works best for us. ;-)