Fix docs #347

aboedo · 2021-08-13T18:15:04Z

our docs for purchases-android were pretty broken. They only pointed to the Purchases type, didn't include much information in general or correctly link to the source code.

I believe this was broken during our modularization project, since we shuffled a lot of stuff around but didn't update the dokka configuration.

This updates dokka to the latest version (as of writing), updates the format, and uses the Multi-Module setup from dokka so that we can link stuff nicely even if it's separated into packages.

Before	After

I've already published the new version, you can see it in action in https://sdk.revenuecat.com/android/index.html.

Also, I absolutely suck at gradle, please point out if there are better ways to do things.

aboedo · 2021-08-13T18:15:23Z

.circleci/config.yml

@@ -132,7 +132,7 @@ jobs:
      - android/restore-build-cache
      - run:
          name: Dokka
-          command: ./gradlew dokka
+          command: ./gradlew dokkaHtmlMultiModule


new command for generating stuff in a modularized setup

aboedo · 2021-08-13T18:15:39Z

build.gradle

-        classpath "org.jetbrains.dokka:dokka-gradle-plugin:0.10.0"
+        classpath "org.jetbrains.dokka:dokka-gradle-plugin:1.4.32"


this is the reason the docs look so much nicer now

Good to see they have fixed that horrible layout haha

aboedo · 2021-08-13T18:15:59Z

build.gradle

+apply plugin: 'org.jetbrains.dokka'
+
+tasks.dokkaHtmlMultiModule.configure {
+    outputDirectory.set(file("docs"))
+    includes.from("README.md")
+}


this is the parent config

aboedo · 2021-08-13T18:16:18Z

docs/index.html

-<!DOCTYPE html>
 <html>
-<head>
-	<meta http-equiv="refresh" content="0; url=purchases/index.html" />
-</head>
-<body>


not sure this should have been versioned in the first place, but not looking to change that right now

So I created this docs/index.html to redirect to purchases/index.html. This was so accessing https://sdk.revenuecat.com/android/ would redirect to https://sdk.revenuecat.com/android/purchases/index.html. Dokka was creating the files in purchases because their multi module support was horrible. I think we can un-version it now because dokka is creating an index.html where we want it to be.

ohhh interesting, makes sense. I'll kill it then

aboedo · 2021-08-13T18:16:41Z

public/build.gradle

+    dokkaSourceSets {
+        configureEach {
+            reportUndocumented.set(true)
+            includeNonPublic.set(false)
+            skipDeprecated.set(true)
+
+            externalDocumentationLink {
+                url.set(uri("https://developer.android.com/reference/package-list").toURL())
+            }
+            sourceLink {
+                localDirectory.set(file("src/main/java"))
+                remoteUrl.set(uri("https://github.com/revenuecat/purchases-android/blob/master/public/src/main/java").toURL())
+                remoteLineSuffix.set("#L")
+            }
+        }
+    }
+}


this should be done in each package that has at least one public type

aboedo · 2021-08-13T18:17:07Z

purchases/build.gradle

@@ -31,55 +32,23 @@ dependencies {
    testImplementation 'org.assertj:assertj-core:3.13.2'
 }

-apply plugin: 'com.vanniktech.maven.publish'


this was the original problem: we still had dokka set up for the purchases module, but a lot of stuff lives in public now

…odules.

beylmk · 2021-08-14T00:30:02Z

purchases/build.gradle

-        skipDeprecated = true
-        // Allows linking to documentation of the project's dependencies (generated with Javadoc or Dokka)
-        // Repeat for multiple links
-        externalDocumentationLink {


did we confirm the trailing slash is not required?

I actually never got this to work. Does this work in the new version? I was looking for an example but I can't find it. I think we don't have any public link to the billing client anymore and everything is in the google module

happy to remove it, I kept it around for the sake of having everything that we had before

Agreed, I would keep it the same it was before

beylmk · 2021-08-14T00:34:30Z

public/build.gradle

+}
+
+tasks.dokkaHtmlPartial.configure {


would be nice to pull the common configuration stuff out somehow, but i'm also not great at gradle...

This could be extracted to a file like library.gradle and call it dokka.gradle. Then apply the file doing:

apply from: "$rootProject.projectDir/dokka.gradle"

But there's one thing that changes: the source directory. It is src/main/java for public and src/main/kotlin for purchases. I am not sure how to change that part in each of the modules. Maybe setting just that part in the module's gradle inherits everything from the dokka.gradle and changes that part for the module. Something like:

apply from: "$rootProject.projectDir/dokka.gradle" ... dokkaSourceSets { configureEach { sourceLink { localDirectory.set(file("src/main/java")) remoteUrl.set(uri("https://github.com/revenuecat/purchases-android/blob/main/public/src/main/java").toURL()) } } }

We should move everything to src/main/kotlin although not a priority at all.

As an example. I found the arrow project does it this way https://github.com/arrow-kt/arrow/blob/ee319ace7df8dd05001406b3727aa3ed90188e07/arrow-libs/gradle/apidoc-creation.gradle

They have a apidoc-creation.gradle, and they do " ${relativeProjectPath('src/main/kotlin')}" to figure out the relative path of the source files. Then they apply the gradle file in each of the modules https://github.com/arrow-kt/arrow/blob/2569ece084a0ace0a77c0ed126b452babe69d52b/arrow-libs/core/arrow-annotations/build.gradle#L7. They have a gradle property https://github.com/arrow-kt/arrow/blob/main/arrow-libs/gradle.properties#L80 pointing to that file.

agreed, I think that's the intent of the dokkaHtmlPartial clauses.
I started by trying to have as much stuff in a single file as possible but kept running into issues, so I ended up going with this path for the sake of not spending too much time on this.

I can give it another shot if you think it's important to do now, otherwise we can add it to the backlog

I don't think it's important to do right now 🙂

aboedo self-assigned this Aug 13, 2021

aboedo commented Aug 13, 2021

View reviewed changes

aboedo requested a review from a team August 13, 2021 18:17

aboedo added 8 commits August 13, 2021 16:08

fixed docs generation so that it includes both public and purchases m…

c148ff8

…odules.

updated dokka task

d23285e

fixes some issues in the doc generation

91cc79f

cleanup and fixes

1958482

cleanup of properties

012d702

more cleanup and applied fixes to the other package

d36f5e1

updated circleci task for dokka

6f28f16

update branch name in repo link

e2dccc0

aboedo force-pushed the fix_docs branch from 4b07e63 to e2dccc0 Compare August 13, 2021 19:09

beylmk reviewed Aug 14, 2021

View reviewed changes

unversioned docs/index.html

de4a95a

vegaro approved these changes Aug 17, 2021

View reviewed changes

aboedo merged commit 22a548b into main Aug 18, 2021

aboedo deleted the fix_docs branch August 18, 2021 14:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix docs #347

Fix docs #347

aboedo commented Aug 13, 2021

aboedo Aug 13, 2021

aboedo Aug 13, 2021

vegaro Aug 16, 2021

aboedo Aug 13, 2021

aboedo Aug 13, 2021

vegaro Aug 16, 2021

aboedo Aug 16, 2021

aboedo Aug 16, 2021 •

edited

Loading

aboedo Aug 13, 2021

aboedo Aug 13, 2021

beylmk Aug 14, 2021

vegaro Aug 16, 2021

aboedo Aug 16, 2021

vegaro Aug 17, 2021

beylmk Aug 14, 2021

vegaro Aug 16, 2021

aboedo Aug 16, 2021

vegaro Aug 17, 2021

		classpath "org.jetbrains.dokka:dokka-gradle-plugin:0.10.0"
		classpath "org.jetbrains.dokka:dokka-gradle-plugin:1.4.32"

		}

		tasks.dokkaHtmlPartial.configure {

Fix docs #347

Fix docs #347

Conversation

aboedo commented Aug 13, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aboedo Aug 16, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aboedo Aug 16, 2021 •

edited

Loading