Akka-http: Migrate docs from Akka/Akka here, using Paradox

[ktoso]

We want to move documentation from:

• https://github.com/akka/akka/tree/master/akka-docs/rst/scala/http
• https://github.com/akka/akka/tree/master/akka-docs/rst/java/http

To this repo. Both text and tests of course.

The docs should be generated using https://github.com/lightbend/paradox which will allow us to "aggregate" them together with other akka docs into an "aggregated view" if someone wants that.

Otherwise the docs will be separate so this will allow more focused browsing and searching.

The theme for now can be the plain Akka one, though we'll likely want to differentiate a little bit, maybe just by adding HTTP in the header or sth.

I will attempt to make the first step of this move, and then would like to ask for help migrating all the docs to paradox.

[ktoso]

Docs will then be published to http://doc.akka.io/api/akka-http/10.0/

[patriknw]

Then we would probably want to implement the automatic rst->paradox converter first. It's then needed sooner than I first thought of. Note that @drewhk is interested in writing the converter tool.

[ktoso]

We could move sphinx, but since that will need re-working paths of includes anyway I thought it might be better to take the hit all at once. Open to suggestions ofc

[patriknw]

yeah, it all depends on how big the effort is. Let's spend at most 2 days on the converter tool and then community can hopefully do the actual conversion and manual adjustments.

[ktoso]

Yeah, there was some intent to help signalled on gitter, I hope we'll be able to move it over without too much pain

[drewhk]

I can do a timeboxed try with Laika to estimate the effort. I used it before on akka-docs (for different purpose) and it is not rocket science.

[ktoso]

It can be "mostly" correct, we'll fix the rest manually

[johanandren]

As far as I got playing around with Laika: https://github.com/johanandren/akkadocs-sphinx2paradox

[johanandren]

Heh, maybe I should add exactly how far that was:

Some special stuff still not covered, includecode works but not includecode2 yet, warning/info boxes becomes regular text with bold header. Got some warning from some markup, can't remember exactly what it was.

[jonas]

@johanandren I added a few additional code on top of your repo here: https://github.com/jonas/akkadocs-sphinx2paradox

The current state (with includecode2 and @ref[] directives disabled) can be seen here: https://jonas.github.io/akkadocs-sphinx2paradox/

A list of things to resolve:

• [x] Convert footnotes.
• [x] Convert tables (there only seem to be a couple)
• [x] Convert a couple of cross links.
• [x] Figure out how to convert figure captions and definition lists? New Paradox directives?
• [x] Some issues with @@snip which is less flexible (and forgiving) in what it can handle, e.g.:
  
  
  
  • Only one #tag per snippet, and a tag cannot appear multiple times: a Paradox feature request?
  
  
  • Doc code does not always "close" the snippet correctly.
  
  
• [x] @ref[]() requires that the file being linked to is known. Could be cached on disk from collected InternalLinkTargets.
• [x] Figure out how to convert toctree properly using @@toc and @@@ index.

Dependencies:

• lightbend/paradox/issues/7

[ktoso]

This is great, I'll move existing docs into this repo today and get the build to work as well.
Looking forward to the next step from your side after that then, thanks a lot!

[jonas]

WIP branch: https://github.com/jonas/akka-http/tree/wip-paradox
WIP Paradox site: https://jonas.github.io/akka-http/

[ktoso]

Does that mean it does not make sense for us to import historic commits? https://github.com/akka/akka-http/pull/289
Would you be able to PR this soon?

[jrudolph]

@jonas we've rewritten the whole history one last time again to include history for documentation as well but it's now missing a few infrastructure and auxiliary files. Depending on what's your base for the rewriting you/we may have to copy over other files over from akka again. It's also fine if you continue working on your current version (trying to rebase to our new state might conflict) and we polish just the final result coming out from your conversion. WDYT?

[jonas]

@jrudolph I've rebased on top of the updated rewritten history you pushed.

The next question is how close to working the conversion needs to be before such a PR is acceptable. The main blocker right now is extracting link text for the ~500 cross-reference (likely doable with some sed scripts to feed the conversion tool) and making the directive snippets work. The latter will be a lot of work and I am wondering if it would be better to leave it broken for now and instead try to solve it via #11 or some interim preprocessing tool that extracts directive docs or snippets from code comments.

[ktoso]

I think an initial PR would be good already. For the "needs lots of work" perhaps we'd get some help from the community

[ktoso]

Not marking as resolved yet, until we've made it to an actual rendered page on doc.akka.io :)

[jonas]

I saw the ticket about redirecting akka.github.io/akka-http to doc.akka.io/http. Do we also need a ticket for porting the theme? Let me know how I can help.

[ktoso]

Yes and no, I was hoping to get a designer help us do a proper new theme.
One company has ignored my quote inquiry (boooo!), so I'll try another one ;-)

[ktoso]

AKA we don't want to spend a lot of time on porting the theme just jet

[ktoso]

Done thanks to the relentless efforts of @jonas! Thanks a lot!
Let us know if you'd like to continue being strongly involved once the docs things are all said and done btw :-)

[jonas]

@ktoso 👍 I would like to keep contributing as time permits. For now I will mainly focus on tooling and documentation.