orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you
https://orchid.run
GNU General Public License v3.0
513 stars 53 forks source link

sbt plugin, fwiw #324

Closed swaldman closed 4 years ago

swaldman commented 4 years ago

i've only just begun to try out Orchid, but i work mostly in Scala and my preferred build environment is sbt.

for what it's worth, i've written a plugin to integrate Orchid into sbt (cribbing a lot from the Maven plugin). it seems to work, though i'm sure its edges are very rough. i would love any feedback.

It's here https://github.com/swaldman/sbt-orchid

thanks!

cjbrooks12 commented 4 years ago

That's looks great! I've never worked with Scala or used SBT, but it looks like it's doing what it should. I've intentionally tried to keep these runners as simple as possible so that Orchid isn't locked into any one of them, so if it runs and doesn't crash, then it's probably set up perfectly 🙂

How would you feel about adding your plugin here, to be an official Orchid runner?It would be nice to have it published alongside the other runners and plugins so they all have the same version number.

swaldman commented 4 years ago

Thanks!

I'm very glad to have the sbt plugin integrated here.

Build integration may be a bit weird, though. I think it should be doable with Gradle's scala plugin. But it will take some nondefault configuration to publish the artifact under the sbt-plugin-required convention of <plugin-name>_<scala-major-version>_<sbt-major-version> (so sbt-orchid gets published in a repository directory called sbt-orchid_2.12_1.0 even while the jar files within that directory look like plain sbt-orchid-<version-number>.jar). I'm not sure I've seen an example of an sbt plugin built and published with Gradle, but it shouldn't be rocket science.

cjbrooks12 commented 4 years ago

I'm not looking to get the SBT plugin integrated directly with Gradle, just added as a subdirectory here so the CI deploy script can run the SBT commands needed for that subdirectory. The Maven plugin isn't integrated into the full Gradle build either.

Basically, if you could make a PR adding the SBT plugin to the buildSrc/orchidSbtPlugin directory (or whatever SBT needs it named as) and include build.sh, test.sh, and deploy.sh scripts in that dir with the relevant commands, then we should be good to go and I can hook it up to the CI builds. And if it could be set up such that SBT/Scala does not need to be a system-wide dependency, that would be ideal, something like the Gradle or Maven wrappers. A quick search and I found sbt-extras which seems to be what I'm thinking of, but if that doesn't work we can figure something else out.

Also, what exactly is an SBT plugin published as? Just a normal Maven dependency JAR? Will publishing it to JCenter be sufficient, or are there extra steps needed to add it to an SBT plugin registry or something like that?

swaldman commented 4 years ago

The sbt wrapper script from paulp/sbt-extras works great. I use it a lot.

An sbt plugin is published to ordinary Maven repositories, but the naming is a bit unusual. Here's an example. The Scala language version and SBT major version are embedded in the project name, but not in the individual jar file names. SBT knows how to publish its own plugins, though, and should very happily publish them to bintray. I haven't published to bintray, but I suspect that sbt's support for that (especially credential location and format) is pretty conventional.

I can certainly write build and test. But if the version is going to sync with Orchid's, I'll need that as an environment variable or something. Would deploy in this context just be publishing to bintray?

cjbrooks12 commented 4 years ago

This is helpful, thank you. Yes, the deploy should just be getting it published to Bintray, I would assume the plugin does all the hard stuff and formats everything properly out-of-the-box. The following environment variables will be available during publishing:

And any other info that might be needed would probably be in this file, but just let me know if there's any other credentials you'll need. Thanks for working on this feature, this is really exciting!

swaldman commented 4 years ago

Well, fwiw I've posted an attempt at a pull request.

https://github.com/JavaEden/Orchid/pull/328

I'll close this issue, and we can continue the conversation over there.