Unable to get the versioning plugin configured using Maven

[PMarci]

Describe the bug After failing to get the versioning working on a fork of a company project, I tried to do it with the maven example project. Based on this and this I modified the pom.xml to this:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.jetbrains.kotlin.examples</groupId>
    <artifactId>kotlin-maven-example</artifactId>
    <version>1.0.2</version>
    <properties>
        <kotlin.version>1.6.10</kotlin.version>
        <dokka.version>1.6.10</dokka.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-stdlib</artifactId>
            <version>${kotlin.version}</version>
        </dependency>
        <dependency>
            <groupId>org.jetbrains.dokka</groupId>
            <artifactId>versioning-plugin</artifactId>
            <version>${dokka.version}</version>
        </dependency>
    </dependencies>

    <build>
        <sourceDirectory>${project.basedir}/src/main/kotlin</sourceDirectory>

        <plugins>
            <plugin>
                <artifactId>kotlin-maven-plugin</artifactId>
                <groupId>org.jetbrains.kotlin</groupId>
                <version>${kotlin.version}</version>

                <executions>
                    <execution>
                        <id>compile</id>
                        <phase>compile</phase>
                        <goals>
                            <goal>compile</goal>
                        </goals>
                    </execution>

                    <execution>
                        <id>test-compile</id>
                        <phase>test-compile</phase>
                        <goals>
                            <goal>test-compile</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

            <plugin>
                <groupId>org.jetbrains.dokka</groupId>
                <artifactId>dokka-maven-plugin</artifactId>
                <version>${dokka.version}</version>
                <executions>
                    <execution>
                        <phase>pre-site</phase>
                        <goals>
                            <goal>dokka</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <sourceLinks>
                        <link>
                            <path>${project.basedir}</path>
                            <url>https://github.com/JetBrains/kotlin-examples/blob/master/maven/dokka-maven-example
                            </url>
                            <lineSuffix>#L</lineSuffix>
                        </link>
                    </sourceLinks>
                    <outputDir>${project.basedir}/public</outputDir>
                    <dokkaPlugins>
                        <plugin>
                            <groupId>org.jetbrains.dokka</groupId>
                            <artifactId>versioning-plugin</artifactId>
                            <version>${dokka.version}</version>
                        </plugin>
                    </dokkaPlugins>
                    <pluginsConfiguration>
                        <org.jetbrains.dokka.versioning.VersioningConfiguration>
                            <version>${project.version}</version>
                            <olderVersionsDir>${project.basedir}/old</olderVersionsDir>
                        </org.jetbrains.dokka.versioning.VersioningConfiguration>
                    </pluginsConfiguration>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

as well as a stab in the dark with variations of

                    <pluginsMapConfiguration>
                        <org.jetbrains.dokka.versioning.VersioningConfiguration>{ "version": "1.2.3", "olderVersionsDir": "${project.basedir}/old" }</org.jetbrains.dokka.versioning.VersioningConfiguration>
                    </pluginsMapConfiguration>

in the configuration tags. Even when manually placing different outputs into the olderVersionsDir folder, the version dropdown was never generated. Also, the version was never inserted into version.json:

{"version":""}

I debugged the dokka:dokka goal, placing various watch and break points into org.jetbrains.dokka.versioning.VersioningConfiguration, but none were triggered. At some other position in the code, I once saw the contents of the org.jetbrains.dokka.versioning.VersioningConfiguration tags in pom.xml serialized with tags and all, and a property alongside it marking that the format was XML. I don't remember exactly where. This is what inspired me to try the json version as well, as well as the guidance on the version doc page's examples section.

Expected behaviour I expected the versions dropdown to be generated in the output, similarly to how it works with the dokkaHtmlMultiModule task in the gradle example, which I confirmed works as expected. I also expected the automatic management of the olderVersionsDir to work as described, however I haven't managed to move a folder once using Maven. Based on some discussion I saw here on various issues here, I got the feeling the maven plugin is probably not even capable of what I expect, however this isn't reflected in the documentation.

Screenshots There aren't any visible aspects to this other than the dropdowns not being present, which I trust you can picture.

To Reproduce Try to get the maven example project to generate the dropdown and to manage the past outputs using my pom.xml or any other configuration.

Dokka configuration Contained in the POM.

Installation

• Operating system: macOS
• Build tool: Gradle v7.3 from the project/Maven 3.8.1
• Dokka version: 1.5.0/1.6.0/1.6.10

Are you willing to provide a PR? As soon as a working configuration is discovered, it should be added as a separate example, much like the examples/gradle folder.

[PMarci]

Note: before the dokka:dokka goal attempts I also ran mvn package to populate the target directory.

[expjoschmidt]

@PMarci Any breakthroughs in the last week?

Is there any mechanism for increasing importance of an issue? I am running into this exact same problem. At best the docs are hard to understand and at worst there is a bug.

One thing potentially worth noting is I've requested access to the Slack channel that the docs point to. Once I have access I plan to escalate that way.

[PMarci]

@expjoschmidt None. I ended up provisionally creating a shell script that moves the current documentation to a versioned subfolder and creates the version.json file. All this in the hopes that if and when this is eventually fixed I'll be able to replace it with the plugin and point olderVersionsDir to the docs already accumulated. I can share that script with you if you want.

[expjoschmidt]

@PMarci I would like that script please. It sounds like a nice stop-gap.

[IgnatBeresnev]

Hi! Unfortunately, our maven runner is rather simple and many advanced features may not work as expected or at all (i.e multimodule builds don't work at all, I suspect versioning as well).

We'll definitely get to supporting these features for maven sometime, but currently there are no immediate plans to work on it as we're focusing on making dokka stable

[PMarci]

@expjoschmidt Here, I published it as a gist: https://gist.github.com/PMarci/59500c1512fcd67c940f326620242e62

EDIT: For the sake of clarity, this was placed in the project root, as the CI/CD for the project is set up for GitLab Pages, where the docs have to be in a folder in the root named public. Dokka was already configured to output to ${project.basedir}/public/ as you can see from my pom.xml in the OP.

[expjoschmidt]

Thank you @PMarci I'll take a look!

[vmishenev]

<org.jetbrains.dokka.versioning.VersioningPlugin> should be used instead of <org.jetbrains.dokka.versioning.VersioningConfiguration>.

The correct configuration for the versioning plugin:

                    <pluginsConfiguration>
                        <org.jetbrains.dokka.versioning.VersioningPlugin>
                            <version>${project.version}</version>
                            <olderVersionsDir>${project.basedir}/old</olderVersionsDir>
                        </org.jetbrains.dokka.versioning.VersioningPlugin>
                    </pluginsConfiguration>