consolidate java/scala content

[patriknw]

With the @java and @scala tags and the multi-tab code snippets it's possible to consolidate java and scala content into same .md file and avoid duplication.

Example: https://raw.githubusercontent.com/akka/akka/master/akka-docs/src/main/paradox/scala/guide/tutorial_1.md

• actors.md - @richard-imaoka
• ... you can help too! Please write a comment what you're working on to avoid duplicate work.

Can be done piece-by-piece.

[atiqsayyed]

@patriknw I'd be very happy to take this up, could you please explain a little more of what are we planning to do? And what are the areas that we'll be focussing on?

[raboof]

@atiqsayyed that would be great!

The process is as follows:

• Mention in this issue which pages you're planning to merge
• Compare a file in akka-docs/src/main/paradox/java/... with the same one under akka-docs/src/main/paradox/scala/.... They should cover the same contents, but one is for Java and the other is for Scala. The 'compare files' feature of IntelliJ IDEA is a nice tool for this.
• Update the file in the scala folder to contain both the Scala and Java content. You may use:
  • @scala and @java directives for inline text
  • @@@ div { .group-scala } for blocks
  • code blocks become tabbed
• Replace the 'java' version of the page with a symlink:
  • Remove the old version (git rm akka-docs/src/main/paradox/java/...)
  • Create a symlink (cd akka-docs/src/main/paradox/java; ln -s ../scala/... ...; cd -)
  • Add the symlink to git (git add akka-docs/src/main/paradox/java/...)
• Test your changes (sbt akka-docs/paradox, see CONTRIBUTING.md for details, check both the Java and Scala versions)

You could look at https://github.com/akka/akka/pull/23039/files as an example - it's probably best to contribute PR's on a page-per-page basis at least at first. Feel free to let us know if you have any questions/problems!

[richardimaoka]

Hi just to let you know and to avoid duplicated work, I already started on paradox/scala/actors.md and paradox/java/actors.md. I'm going to submit a PR soon. For other .md files I did not start the work yet.

[atiqsayyed]

Okay.. Unfortunately i also started with actors :D
No Issues, I can work on other files. @richard-imaoka thanks for putting it here..

[ktoso]

Yep, thanks for coordinating :-)
I'll put a list who works on what in the first post.
Are you going to pick up something else @atiqsayyed ?

[richardimaoka]

@atiqsayyed I am really sorry about that ... I started working on actors.md about a week ago, so I should have submitted a PR earlier so that we could avoid the conflict.

Let's coordinate this using the below list (if the core team prefers, please move the list to the 1st comment on this issue).

The core team or I can mark what @atiqsayyed is working on at the moment.

/java

• /java/actors.md - @richardimaoka Merge akka-docs/paradox/scala/actors.md and java/actors.md #23079
• /java/agents.md - @richardimaoka Merge paradox/scala/agents.md and java/agents.md #23080
• /java/camel.md - @richardimaoka Merge paradox/scala/camel.md and java/camel.md #23456
• /java/cluster-client.md - @richardimaoka Merge paradox/scala/cluster-client.md and java/cluster-client.md #23096
• /java/cluster-metrics.md - @richardimaoka Merge paradox/scala/cluster-metrics.md and java/cluster-metrics.md #23098
• /java/cluster-sharding.md - @richardimaoka Merge paradox/scala/cluster-sharding.md and java/cluster-sharding.md  #23112
• /java/cluster-singleton.md - @richardimaoka Merge paradox/scala/persistence-query-leveldb.md and java/persistence-query-leveldb.md #23188
• /java/cluster-usage.md - @richardimaoka Merge paradox/scala/cluster-usage.md and java/cluster-usage.md  #23154
• /java/dev
• /java/dispatchers.md - @richardimaoka More description about blocking operations  #22998
• /java/distributed-data.md - @gosubpl Merge distributed-data.md (scala and java versions into one) (#23052) #23395
• /java/distributed-pub-sub.md - @richardimaoka Merge paradox/scala/distributed-pub-sub.md and java/distributed-pub-sub.md #23266
• /java/event-bus.md - @richardimaoka Merge paradox/scala/event-bus.md and java/event-bus.md  #23155
• /java/extending-akka.md - @richardimaoka Merge paradox/scala/extending-akka.md and java/extending-akka.md #23156
• /java/fault-tolerance-sample.md - @richardimaoka Merge java/fault-tolerance-sample.md with scala/fault-tolerance-sample.md #23160
• /java/fault-tolerance.md - @richardimaoka Merge paradox/scala/fault-tolerance.md and java/fault-tolerance.md #23172
• /java/fsm.md - @richardimaoka Merge paradox/scala/fsm.md and java/fsm.md #23190
• /java/futures.md - @richardimaoka Merge paradox/scala/futures.md and java/futures.md #23397
• /java/howto.md - @richardimaoka Merge paradox/scala/howto.md and java/howto.md  #23159
• /java/index-actors.md @raboof Remove deprecated ActorDSL section from docs #23330
• /java/index-futures.md @raboof Link index-futures.md and index-network.md #23331
• /java/index-network.md @raboof Link index-futures.md and index-network.md #23331
• /java/index-utilities.md @raboof Move 'java 8 compatibility' under 'utilities' #23232
• /java/index.md @raboof Move 'java 8 compatibility' under 'utilities' #23232
• /java/io-tcp.md - @richardimaoka Merge paradox/scala/io-tcp.md and java/io-tcp.md  #23163
• /java/io-udp.md - @richardimaoka Merge paradox/scala/io-udp.md and java/io-udp.md #23164
• /java/io.md - @richardimaoka Merge paradox/scala/io.md and java/io.md #23168
• /java/logging.md @raboof Merge java and scala versions of logging.md #23332
• /java/mailboxes.md - @richardimaoka Merge paradox/scala/mailboxes.md and java/mailboxes.md #23191
• /java/persistence-query-leveldb.md - @richardimaoka Merge paradox/scala/persistence-query-leveldb.md and java/persistence-query-leveldb.md #23188
• /java/persistence-query.md - @richardimaoka Merge paradox/scala/persistence-query.md and java/persistence-query.md #23175
• /java/persistence-schema-evolution.md - @richardimaoka Merge paradox/scala/persistence-schema-evolution.md and java/persistence-schema-evolution.md #23189
• /java/persistence.md - @richardimaoka Merge paradox/scala/persistence.md and java/persistence.md  #23226
• /java/remoting-artery.md - @richardimaoka Merge paradox/scala/remoting-artery.md and java/remoting-artery.md #23258
• /java/remoting.md
• /java/routing.md - @richardimaoka Merge paradox/scala/routing.md and java/routing.md #23192
• /java/scala-compat.md - @richardimaoka Merge akka-docs/paradox/scala/actors.md and java/actors.md #23079
• /java/scheduler.md - @richardimaoka Merge paradox/scala/scheduler.md and java/scheduler.md  #23169
• /java/serialization.md - @richardimaoka Merge paradox/scala/serialization.md and java/serialization.md #23171
• /java/testing.md
• /java/typed-actors.md - @gosubpl Merge scala & java content for typed-actors.md docs (#23052)  #23422
• /java/typed.md - @gosubpl Merge scala & java content for typed.md docs (#23052) #23407

/java/stream

• /java/stream/index.md - @atiqsayyed Merged the document from java/stream/index and scala/strea/index #23539
• /java/stream/stages-overview.md - @atiqsayyed Merged the document from java/stream/stages-overview and scala/stream… #23085
• /java/stream/stream-composition.md - @atiqsayyed Merged the document from java/stream/stages-overview and scala/stream… #23085
• /java/stream/stream-cookbook.md - @atiqsayyed Merge akka-docs/paradox/scala/stream/stream-cookbook.md and java/stream-cookbook.md #23134
• /java/stream/stream-customize.md - @atiqsayyed Merge scala/stream/stream-customize.md and java/stream/stream-customi… #23181
• /java/stream/stream-dynamic.md - @atiqsayyed Merge scala/stream/stream-customize.md and java/stream/stream-customi… #23181
• /java/stream/stream-error.md - @atiqsayyed Merge scala/stream/stream-error.md and java/stream/stream-error.md #23183
• /java/stream/stream-flows-and-basics.md - @atiqsayyed Merged the document from java/stream/stages-overview and scala/stream… #23085
• /java/stream/stream-graphs.md - @naferx Merge content of stream graphs.md #23455
• /java/stream/stream-integrations.md - @naferx merge content of stream-integrations.md #23203
• /java/stream/stream-introduction.md - @naferx merge content of stream-introduction.md #23204
• /java/stream/stream-io.md - @naferx merge content of stream-io.md #23236
• /java/stream/stream-parallelism.md - @naferx merge content of stream-parallelism.md #23206
• /java/stream/stream-quickstart.md - @naferx merge content of stream-quickstart.md #23212
• /java/stream/stream-rate.md - @naferx merge content of stream-rate.md #23218
• /java/stream/stream-testkit.md - @naferx merge content of stream-testkit.md #23213

[atiqsayyed]

I'll work on

/java/stream/index.md
 /java/stream/stages-overview.md

to start with and try to do as many as possible...
If someone is picking anything please share it here.. Thanks!

[gosubpl]

For me: /java/distributed-data.md :)

[gosubpl]

And I will also tackle two other: /java/typed-actors.md /java/typed.md

[richardimaoka]

Sure, recorded @gosubpl's items, as well as @atiqsayyed's PR.

[atiqsayyed]

created pull request for stream-cookbook.md

[naferx]

hey @richard-imaoka , I'll give it a try to /java/stream/stream-integrations.md and
/java/stream/stream-introduction.md

[richardimaoka]

OK, marked the items for @atiqsayyed and @naferx

[richardimaoka]

Raised the above issue in akka-http 😃

[richardimaoka]

Now it looks like /java/stream/index.md is the last one 😃

[raboof]

Yes, excellent ;).

I couldn't resist trying out what the pages now look like when I remove the page refresh on language switch (6dae337), sneak preview at http://pi.bzzt.net/akka-docs/ . Needs some more careful thinking/work before we can actually put it live, but you can experience how the language switching can now be nice and smooth there :)

[richardimaoka]

Yep, the new language switch is much smoother. I really like it! 👍

As far as I can tell, remaining tasks are:

1. Redirect on the current versoin: (e.g.) /scala/actors.html to /actors.html
2. Suggest redirect to the page without /scala or /java when you visit a page for an older version.

https://doc.akka.io/docs/akka/2.4/scala/actors.html

Is 1. more for server-side settings which the core team takes care, and 2. might be a trick in JavaScript the community can figure out?

[raboof]

In fact the redirection can be done in the repo, too - see https://github.com/akka/akka/pull/23544/files#diff-b5f788d092e9bf5e9eb7c8cb3365cf83 . I'll update that PR to resolve merge conflicts today and then perhaps we should just merge it.

I suppose we should make a separate ticket for re-introducing the 'suggest the latest version of this page' functionality? Though I think our SEO is now better so people don't end up on older versions of the docs so often anymore ;)

[raboof]

I added #23869 for the 'latest version' box. I think this one can now be closed! Many thanks to all of you who have been a tremendous help in achieving this!