Provide task that runs an embedded documentation server

[jroper]

Paradox should provide a command that runs an HTTP server, and then runs the documentation generation task in watch sources mode. sbt code that does this using an embedded python http server can be found here:

https://github.com/lagom/lagom.github.io/blob/template/build.sbt#L31

[dwijnand]

This not-exactly-Paradox-specific issue has been deferred sbt-site: https://github.com/sbt/sbt-site/pull/73 which was recently merged and cut as v1.2.0-RC1.

[ktoso]

Glad to see it's implemented there in scala and not calling out to python, making it hard to develop e.g. for windows people (and yeah, windows people do contribute to docs quite enough to care about their wellbeing ;-)) Too bad that not akka http there but oh well, whatever works.

[jroper]

With regards to using sbt-site to achieve this, would the intent be to generate the whole website using sbt-site? Or just a mockup for the purposes of rendering the documentation during development? In my experience, as long as you want to publish documentation for multiple different versions of a product, the website generation can't be tied to the documentation build, since it needs to aggregate multiple documentation builds.

[2m]

I agree that we need to separate these two use-cases and come up with solutions for both of them. For example when rendering documentation during development it is important to redirect links to API classes to the locally generated files. We have a command for that in Alpakka. (maybe it would better be implemented using a custom configuration, as Paradox now has support for it).

And whole site generation is quite well solved by tech-hub currently.

[myfear]

Did anything happen here lately?

[2m]

In Alpakka and other Akka satellite projects we are now using sbt-site for that. So previewSite generates paradox documentation and starts a server to preview it.