Documenting the project website (#105)

.github/workflows/document-deploy.yml

@@ -0,0 +1,70 @@
+name: document-deploy
+on:
+ pull_request:
+ branches: [ main ]
+ types: [ closed ]
+
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+concurrency:
+ group: 'pages'
+ cancel-in-progress: true
+
+jobs:
+ document-deploy:
+ environment:
+ name: 'github-pages'
+ url: ${{ steps.deployment.outputs.page_url }}
+
+ runs-on: macos-latest
+
+ if: ${{
+ github.event.pull_request.merged &&
+ contains(github.event.pull_request.labels.*.name, 'documentation')
+ }}
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Setup JDK 17
+ uses: actions/setup-java@v4
+ with:
+ distribution: zulu
+ java-version: 17
+
+ - name: Setup Android SDK
+ uses: android-actions/setup-android@v3
+
+ - name: Setup Gradle
+ uses: gradle/gradle-build-action@v3
+ with:
+ gradle-home-cache-cleanup: true
+
+ - name: Setup Python 3.9
+ uses: actions/setup-python@v4
+ with:
+ python-version: '3.9'
+ cache: 'pip'
+
+ - name: Install mkdocs-material via pip
+ run: pip install mkdocs-material
+
+ - name: Build mkdocs-material
+ run: cd documentation && mkdocs build
+
+ - name: Build dokka at runtime
+ run: cd .. && ./gradlew :runtime:dokkaHtml
+
+ - name: Setup Pages
+ uses: actions/configure-pages@v3
+
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v1
+ with:
+ path: 'documentation/site'
+
+ - name: Deploy to GitHub Pages
+ uses: actions/deploy-pages@v2

.github/workflows/gradle-wrapper-validation.yml

@@ -8,8 +8,7 @@ jobs:
  validate:
  runs-on: ubuntu-latest
  steps:
- - name: Checkout
- uses: actions/checkout@v4
+ - uses: actions/checkout@v4
 
  - name: Validate Gradle Wrapper
  uses: gradle/wrapper-validation-action@v2

.gitignore

@@ -11,3 +11,4 @@
 build
 release
 local.properties
+documentation/site

README.md

@@ -1,40 +1,36 @@
-## ComposeInvestigator
+## ComposeInvestigator ![gradle-plugin-version](https://img.shields.io/maven-central/v/land.sungbin.composeinvestigator/composeinvestigator-gradle-plugin?style=flat-square)
 
 Trace the recomposition of a Composable with its cause without any boilerplate code 😎.
 
-This tool was initiated for personal learning and has not been proven necessary for production. However, it can perform the following tasks:
+This tool was initiated for personal learning and has not been proven necessary for production.
+However, it can perform the following tasks:
 
-- Reports if a Composable is skipped during recomposition.
-- Reports if the arguments of a Composable have changed and been recomposed. It can also compare the values before and after the change.
-- Reports if the state values inside a Composable have been modified. It can also compare the values before and after the change.
-- Retrieves the call stack leading up to the invocation of a Composable. This helps identify the specific Composable being recomposed when the same Composable is reused in multiple places.
+- **Reports if a Composable is skipped during recomposition.**
+- **Reports if the arguments of a Composable have changed and been recomposed.** It can also compare the
+ values before and after the change.
+- **Reports if the state values inside a Composable have been modified.** It can also compare the values
+ before and after the change.
+- **Retrieves the call stack leading up to the invocation of a Composable.** This helps identify the
+ specific Composable being recomposed when the same Composable is reused in multiple places.
 
 ---
 
-### Usage
+### Getting Started 
 
-ComposeInvestigator has various runtime APIs, but they are not yet documented. If you want to try it out in advance, you can understand the APIs by checking the runtime test code.
-
-The overall usage will be documented before the stable version is released. In general, it works fine without using any APIs. Just run the app and check the logcat.
-
-### Under the Hood
-
-ComposeInvestigator is developed using a Kotlin compiler plugin. Detailed information will be documented before the stable version is released.
-
----
-
-### Download
-
-ComposeInvestigator is currently in the technical preview stage, and many tests are missing. Therefore, all usage should not take place in production, and unexpected issues may arise.
-
-If you encounter bugs during use or have new feature suggestions, please report them as issues.
+Just add a Gradle plugin like this one:
 
 ```kotlin
 plugins {
- id("land.sungbin.composeinvestigator") version "0.1.0-dev"
+ id("land.sungbin.composeinvestigator") version "<version>"
 }
 ```
 
+You don't need to use any APIs to get started. But if you're looking for a fancier experience,
+consider using the runtime API.
+
+Comprehensive documentation for ComposeInvestigator is available
+on [project website](https://jisungbin.github.io/ComposeInvestigator).
+
 ### Preview
 
 ![image](https://github.com/jisungbin/ComposeInvestigator/assets/40740128/98991bd9-97f2-47a7-9cc9-6f9cd1cda0e3)

build.gradle.kts

@@ -16,6 +16,13 @@ plugins {
  alias(libs.plugins.spotless) apply false
  alias(libs.plugins.gradle.test.logging) apply false
  alias(libs.plugins.gradle.publish.maven) apply false
+ idea
+}
+
+idea {
+ module {
+ excludeDirs = excludeDirs + listOf(file("runtime/api"), file("documentation"))
+ }
 }
 
 buildscript {

compiler-gradle-plugin/gradle.properties

@@ -1,4 +1,2 @@
 POM_NAME=ComposeInvestigator Gradle Plugin
 POM_ARTIFACT_ID=composeinvestigator-gradle-plugin
-
-VERSION_NAME=0.1.0-dev

compiler-hosted/gradle.properties

@@ -1,4 +1,2 @@
 POM_NAME=ComposeInvestigator Kotlin Compiler Plugin (HOST)
 POM_ARTIFACT_ID=composeinvestigator-compiler-hosted
-
-VERSION_NAME=0.1.0-dev

compiler/gradle.properties

@@ -1,4 +1,2 @@
 POM_NAME=ComposeInvestigator Kotlin Compiler Plugin
 POM_ARTIFACT_ID=composeinvestigator-compiler
-
-VERSION_NAME=0.1.0-dev

documentation/docs/advanced.md

@@ -0,0 +1,87 @@
+# Advanced usage
+
+ComposeInvestigator has a nice set of runtime features.
+
+---
+
+### Customizing reporting formats
+
+ComposeInvestigator has a default reporting format that you can see in`ComposeInvestigatorConfig`.
+The two most important of these are organized as variables, so they can be easily changed.
+
+For example, you can change the `invalidationLogger` to modify the reporting format when a
+recomposition occurs, or the `stateChangedListener`to modify the reporting format when a state
+changed.
+
+### Data management classes
+
+ComposeInvestigator has a class, `ComposableInvalidationTrackTable`, for storing data and reporting
+certain events at the right time. This class is initialized as a singleton in every file, so it is
+recommended to use ComposeInvestigator only in debug mode.
+
+To do this, you can disable ComposeInvestigator in Gradle.
+
+``` kotlin
+composeInvestigator {
+ enabled.set(false)
+}
+```
+
+The instance of `ComposableInvalidationTrackTable` created in the current file can be retrieved
+using `currentComposableInvalidationTracker`.
+
+The `ComposableInvalidationTrackTable` has a `currentComposableName` API that allows you to interact
+with the name of the current composable. (You can get the name of the composable, or change it
+temporarily).
+
+``` kotlin
+@Composable fun MyComposable() {
+ val table = currentComposableInvalidationTracker
+
+ val prevName by table.currentComposableName
+ assertEquals(prevName, "MyComposable") // pass
+
+ table.currentComposableName = ComposableName("AwesomeComposable")
+ val newName by table.currentComposableName
+ assertEquals(newName, "AwesomeComposable") // pass
+}
+```
+
+The value of `currentComposableName` is used as the name of the affected composable when certain
+events are reported. If an anonymous composable is reported that doesn't specify a temporary
+composable name, the composable name will always be "anonymous". It's a good idea to use this API
+when appropriate to prevent this from happening.
+
+``` kotlin
+Column(
+ // content: @Composable () -> Unit
+ // 'content' is just argument name. It's not composable name!
+ content = {
+ Text("This Composable name is always <anonymous>.")
+ }
+)
+``` 
+
+To prevent composables from being named anonymously, we are developing an Android lint to help you
+name temporary composables in appropriate situations.
+[(#90)](https://github.com/jisungbin/ComposeInvestigator/issues/90)
+
+### Add custom invalidation callbacks
+
+By default, all composables are registered as recomposition-tracking targets, but you may want to
+duplicate registing them for arbitrary reasons. (If you have a composable that isn't
+recomposition-tracking by default, that's a bug! Please report it).
+
+In that case, you can use the `registerListener` API inside the `ComposableInvalidationTrackTable`
+to register additional recomposition event callbacks for a specific composable. These added
+callbacks can be removed with the `unregisterListener` API.
+
+Adding and removing callbacks to match the lifecycle of a Composable can be cumbersome, which is why
+we provide the `ComposableInvalidationEffect` API, which works similarly to `LaunchedEffect`.
+
+### Add custom status tracking
+
+By default, any state variable that inherits from `State` or `Animatable` is targeted for state
+tracking. However, if you want to enable state tracking for state variables other than `State` and
+`Animatable`, you can use the `State.registerStateObjectTracking` API. For more information, see the
+documentation for that API.

documentation/docs/changelog.md

@@ -0,0 +1,10 @@
+# Change Log
+
+ComposeInvestigator is heavily dependent on the version of Compose Compiler, so the version of
+ComposeInvestigator follows the format [Compose Compiler Version - ComposeInvestigator Version].
+
+---
+
+### 1.5.10-0.1.0
+
+- Initial release.

documentation/docs/index.md

@@ -0,0 +1,38 @@
+# ComposeInvestigator ![gradle-plugin-version](https://img.shields.io/maven-central/v/land.sungbin.composeinvestigator/composeinvestigator-gradle-plugin?style=flat-square)
+
+Trace the recomposition of a Composable with its cause without any boilerplate code 😎.
+
+This tool was initiated for personal learning and has not been proven necessary for production.
+However, it can perform the following tasks:
+
+- **Reports if a Composable is skipped during recomposition.**
+- **Reports if the arguments of a Composable have changed and been recomposed.** It can also compare
+ the values before and after the change.
+- **Reports if the state values inside a Composable have been modified.** It can also compare the
+ values before and after the change.
+- **Retrieves the call stack leading up to the invocation of a Composable.** This helps identify the
+ specific Composable being recomposed when the same Composable is reused in multiple places.
+
+![preview](https://github.com/jisungbin/ComposeInvestigator/assets/40740128/98991bd9-97f2-47a7-9cc9-6f9cd1cda0e3)
+
+---
+
+### Getting Started
+
+Just add a Gradle plugin like this one:
+
+```kotlin
+plugins {
+ id("land.sungbin.composeinvestigator") version "<version>"
+}
+```
+
+You don't need to use any APIs to get started. But if you're
+looking for a fancier experience, consider using the runtime API.
+
+If you want to learn about the runtime API, check out our [advanced](advanced.md) page.
+
+### License
+
+ComposeInvestigator is available under
+the [MIT license](https://github.com/jisungbin/ComposeInvestigator/blob/main/LICENSE).

documentation/docs/internals.md

@@ -0,0 +1,18 @@
+# ComposeInvestigator Internals
+
+ComposeInvestigator is built by utilizing the Kotlin compiler plugin 
+and the open source of the Compose compiler.
+
+---
+
+### Composable call stacks tracking
+
+(TODO)
+
+### Recomposition tracking
+
+(TODO)
+
+### State change tracking
+
+(TODO)

documentation/mkdocs.yml

@@ -0,0 +1,36 @@
+site_name: 'ComposeInvestigator'
+site_url: 'https://jisungbin.github.io/ComposeInvestigator'
+site_description: 'Trace the recomposition of a Composable with its cause without any boilerplate code'
+site_author: 'Ji Sungbin'
+
+repo_name: 'ComposeInvestigator'
+repo_url: 'https://github.com/jisungbin/ComposeInvestigator'
+
+edit_uri: edit/main/docs/
+copyright: 'ComposeInvestigator ⓒ 2024 Ji Sungbin'
+
+theme:
+ name: 'material'
+ font:
+ text: Noto Sans
+ code: Roboto Mono
+ icon:
+ repo: fontawesome/brands/github
+ features:
+ - content.action.edit
+ - content.action.view
+
+markdown_extensions:
+ - admonition
+ - toc:
+ permalink: true
+ - pymdownx.highlight:
+ anchor_linenums: true
+ - pymdownx.superfences
+
+nav:
+ - 'Overview': 'index.md'
+ - 'Advanced': 'advanced.md'
+ - 'Under the Hood': 'internals.md'
+ - 'Change Log': 'changelog.md'
+ - 'Runtime API ⏏': 'https://jisungbin.github.io/ComposeInvestigator/runtime/api/'

gradle.properties

@@ -27,6 +27,7 @@ RELEASE_SIGNING_ENABLED=true
 SONATYPE_AUTOMATIC_RELEASE=true
 
 GROUP=land.sungbin.composeinvestigator
+VERSION_NAME=1.5.10-0.1.0
 
 POM_DESCRIPTION=Trace the recomposition of a Composable with its cause without any boilerplate code.
 POM_INCEPTION_YEAR=2024

gradle/libs.versions.toml

@@ -10,6 +10,7 @@ ktlint = "1.1.1"
 jetbrains-annotation = "24.1.0"
 
 kotlin-core = "1.9.22"
+kotlin-dokka = "1.9.10"
 kotlin-coroutines = "1.8.0"
 
 androidx-activity = "1.8.2"
@@ -32,6 +33,8 @@ gradle-publish-maven = { id = "com.vanniktech.maven.publish", version.ref = "gra
 gradle-test-logging = { id = "com.adarshr.test-logger", version.ref = "gradle-test-logging" }
 gradle-shadow = { id = "com.github.johnrengelman.shadow", version.ref = "gradle-shadow" }
 
+kotlin-dokka = { id = "org.jetbrains.dokka", version.ref = "kotlin-dokka" }
+
 spotless = { id = "com.diffplug.spotless", version.ref = "spotless" }
 
 [libraries]