Simplify the setup of Play docs

[dwijnand]

These are the various "doc things" in Play:

1. playframework/play-doc
2. play documentation
3. play-docs
4. play-docs-sbt-plugin
5. playframework/play-generated-docs
6. playframework/omnidoc

So:

1. play-doc is the Play's homegrown documentation rendering library
2. The documentation directory in the Play repo holds all the reference docs, which includes functioning code snippets, some of which are also tests, and is a separate sbt build that adds the main Play build into the build state.
3. The play-docs project in the main build I don't know how it's used
4. The play-docs-sbt-plugin project I also don't know, and contrary to my gut it isn't an sbt plugin shim around play-docs... it's something else.
5. play-generated-docs is a derivative git repo with the rendering of the docs.

Do we need all this? Let's discuss how to simplify this.

[dwijnand]

With (1) I think it should move into the Play repo, so it can be assimilated and replaced with Paradox.

With (2) I think the build relationship should be flipped and the documentation root project should be a project of the main build.

With (3) and (4) I need to understand better what play-docs and play-docs-sbt-plugin are.

With (5) is the best we can do right now (AFAIK).

[wsargent]

I can explain play-docs and play-docs-sbt-plugin.

Way, way back, there was the idea that when you ran Play, you could always get to the documentation by going to localhost:9000/@documentation and you could write code inside of a running Play app while looking at the documentation. This is what play-docs does in the DocumentationHandler, and play-docs-sbt-plugin is the sbt hook to get all the documentation in place around it.

I've always found this to be lacking. If you have a compile error such that the application can't start, or you mess up build.sbt, you can't read the documentation. So I think most people go to playframework.com/documentation and aren't even aware that there's a built-in documentation sbt plugin.

Frankly, I don't think anyone would miss it if it were gone or replaced by static PDF / zipped HTML pages etc.

[dwijnand]

Ah, yes, makes sense. And play-docs-sbt-plugin (AutoPlugin PlayDocsPlugin) adds play-docs as a library dependency to enable the dynamic rendering.

[ignasi35]

play-generated-docs is a derivative git repo with the rendering of the docs.

NOTE: play-generated-docs is generated using a script that locally builds omnidoc. That local build aggregates all API and ref docs into $FOLDER/omnidoc/target/scala-2.12/omnidoc. Then, the main script copies some bits and pieces from $FOLDER/omnidoc/target/scala-2.12/omnidoc into $FOLDER/play-generated-docs, commits the changes and pushes into https://github.com/playframework/play-generated-docs/.

[mkurz]

Antora seems the way to go 😉