Refactor artifact publishing

[IgnatBeresnev]

Background

The current solution for publishing artifacts is quite restrictive (adding a different repository requires hardcoding it), and the TeamCity configuration we use is neither convenient nor safe to use (it's a single build configuration with checkboxes and input fields that does everything), especially if used by people outside of the Dokka team.

There's an ongoing effort by @aSemy to refactor publishing in #3030, but it tries to keep compatibility with the current solution and TC build configuration, which can get in the way of some improvements. Now might be a good time to re-evaluate our approach to publishing, and to refactor not only the build scripts, but all of publishing in general (including TC configurations), which will allow us to implement long-awaited improvements.

Publishing requirements

There are 3 types of repositories Dokka needs to publish to:

1. Gradle plugin portal.
2. Maven Central (sonatype)
3. Space Maven repositories.

Gradle plugin portal

No specific requirements or complaints about the current solution, so this bit can most likely be reused.

Would be nice to have:

• Updating the version of the publishing plugin to the latest. They introduced some useful features such as --validate-only - as far as I know, this is the only way to test publishing to Gradle Plugin Portal. The update was attempted before, but there were problems (Update com.gradle.plugin-publish 1.2.0 #2919). Maybe with complete refactoring it'll be easier to fix.
• Due to Gradle Runner 2.0 #3131, it's likely that Dokka will have to support two Gradle plugins for a release or two. It would be nice to make the configuration either reusable or copy-pasteable.

Maven Central

Currently, publishing to Maven Central happens in a single run, even though it really consists of 3 steps:

1. The staging repository is initialized
2. All of the artifacts are uploaded
3. The staging repository is closed (as part of the same run), effectively releasing the artifacts into the world.

It might be convenient in some cases, but I'd would like to separate these two steps. So publishing to Maven Central should initialize the staging repository and upload the artifacts there, and that's it. Then we can test the artifacts manually, make sure everything is correct, and close the staging repository ourselves. Otherwise (and how it works now), if something happens during publishing and one of the modules is built incorrectly, we can't do anything about it, because it's all one giant step.

Additionally, for some reason, the staging repository is initialized even if Dokka is being published to Space only - this is a bug (most likely in configuration), it shouldn't happen.

If publishing to staging and closing it are two different actions, we don't need to support the publishing of -SNAPSHOT versions to Maven Central (DokkaPublicationChannel.MAVEN_CENTRAL_SNAPSHOT), as we only use it before the release itself, mostly as a sanity check.

CI-wise, I will likely create a separate build configuration with restricted access, so there's no need to put it under the same task like now.

Space

Dokka currently has a single Space repository for -dev artifacts (maven.pkg.jetbrains.space/kotlin/p/dokka/dev) that we publish to manually. The artifacts include both custom branches that are behind master, and latest master builds, and it is confusing that 1.9.0-dev-130 might actually be behind 1.9.0-dev-120. For downstream users (Google, Stdlib), it is virtually impossible to guess which versions to use if they want latest changes.

For this reason, I'd like to create a second space repository. One will be used for -dev artifacts and it will contain incremental builds of the master branch (likely once a week or upon request), so that the latest -dev artifact is always of the latest master commits. The other will be used for test artifacts, which will be very short-lived and could be built from custom branches.

This means that Dokka must have the ability to publish to two different Space repositories (the dev one is hardcoded now, should it be an environment/build property?).

Would be nice to have:

• The artifacts are not signed now, but -dev artifacts are used by Google, and they've asked us to start signing them. It'd be great if signing could be added as part of this refactoring.

Backward compatibility

The only expectation is: from the outside, the "before" and "after" artifacts should look the same, meaning they must have the same .pom, .module and other contents. The rest can be changed as much as required :)

• The whole DokkaPublicationChannel abstraction can be dropped.
• The single task for publishing can be dropped - having separate tasks would be fine (and maybe even preferable).
• The suffix check can be dropped (it will be hardcoded in the TC build configuration + we will have the staging repo, so little chance of making a mistake unlike now when we have a text input field for all types of repositories, including Maven Central).