Skip to content

Commit 5892717

Browse files
daymxndaymxn
authored
Add documentation for DackkaPlugin (#4026)
* Add Dackka documentation * Added PNG variant of flow diagram * Removed SVG and improved wording * Fixed some grammar mistakes * Added TOC for buildSrc * Fixed some grammar * Fixed explanation about doclava. * Moved docs to DackkaPlugin, and fixed incorrect bug link * Fixed readme pointing to old markdown file * Changed bug link to reflect fixed bug
1 parent 3280a27 commit 5892717

File tree

2 files changed

+115
-15
lines changed

2 files changed

+115
-15
lines changed

‎buildSrc/README.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
## Build Source
2+
3+
This file will be more organized as time progresses. Because a lot of our
4+
plugins and systems require a moderate amount of cognitive overhead to understand,
5+
I thought it best to provide documentation for such systems. You can find the
6+
currently documented systems below:
7+
8+
[Dackka Plugin](src/main/java/com/google/firebase/gradle/plugins/DackkaPlugin.kt)
9+
10+
11+
* Note that this file currently only serves as a table of contents until sufficient documentation has been created.

‎buildSrc/src/main/java/com/google/firebase/gradle/plugins/DackkaPlugin.kt

Lines changed: 104 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -12,20 +12,109 @@ import org.gradle.kotlin.dsl.getByType
1212
import org.gradle.kotlin.dsl.register
1313

1414
/**
15-
* Facilitates the creation of Firesite compliant reference documentation.
16-
*
17-
* This plugin handles a procedure of processes, all registered under the "kotlindoc" task.
18-
*
19-
* Those tasks are:
20-
* - Collect the arguments needed to run Dackka
21-
* - Run Dackka with [GenerateDocumentationTask] to create the initial reference docs
22-
* - Clean up the output with [FiresiteTransformTask] to fix minor inconsistencies
23-
* - Remove the java references generated from the task (we do not currently support them)
24-
* - Copies the output files to a common directory under the root project's build directory
25-
*
26-
* @see GenerateDocumentationTask
27-
* @see FiresiteTransformTask
28-
* @see JavadocPlugin
15+
# Dackka Plugin
16+
17+
The Dackka Plugin is a wrapper around internal tooling at Google called Dackka, which generates
18+
documentation for [Firesite](https://firebase.google.com/docs/reference)
19+
20+
## Dackka
21+
22+
Dackka is an internal-purposed Dokka plugin. Google hosts its documentation on
23+
an internal service called **Devsite**. Firebase hosts their documentation on a
24+
variant of Devsite called **Firesite**. You can click [here](https://firebase.google.com/docs/reference)
25+
to see how that looks. Essentially, it's just Google's way of decorating (and organizing)
26+
documentation.
27+
28+
Devsite expects its files to be in a very specific format. Previously, we would
29+
use an internal Javadoc doclet called [Doclava](https://code.google.com/archive/p/doclava/) - which
30+
allowed us to provide sensible defaults as to how the Javadoc should be
31+
rendered. Then, we would do some further transformations to get the Javadoc
32+
output in-line with what Devsite expects. This was a lengthy process, and came
33+
with a lot of overhead. Furthermore, Doclava does not support kotlindoc and has
34+
been unmaintained for many years.
35+
36+
Dackka is an internal solution to that. Dackka provides a devsite plugin for
37+
Dokka that will handle the job of doclava. Not only does this mean we can cut
38+
out a huge portion of our transformation systems- but the overhead for maintaining
39+
such systems is deferred away to the AndroidX team (the maintainers of Dackka).
40+
41+
## Dackka Usage
42+
43+
The Dackka we use is a fat jar pulled periodically from Dackka nightly builds,
44+
and moved to our own maven repo bucket. Since it's recommended from the AndroidX
45+
team to run Dackka on the command line, the fat jar allows us to ignore all the
46+
miscenalionous dependencies of Dackka (in regards to Dokka especially).
47+
48+
The general process of using Dackka is that you collect the dependencies and
49+
source sets of the gradle project, create a
50+
[Dokka appropriate JSON file](https://kotlin.github.io/dokka/1.7.10/user_guide/cli/usage/#example-using-json),
51+
run the Dackka fat jar with the JSON file as an argument, and publish the
52+
output folder.
53+
54+
## Implementation
55+
56+
Our implementation of Dackka falls into three separate files, and four separate
57+
tasks.
58+
59+
### [GenerateDocumentationTask]
60+
61+
This task is the meat of our Dackka implementation. It's what actually handles
62+
the running of Dackka itself. The task exposes a gradle extension called
63+
[GenerateDocumentationTaskExtension] with various configuration points for
64+
Dackka. This will likely be expanded upon in the future, as configurations are
65+
needed.
66+
67+
The job of this task is to **just** run Dackka. What happens after-the-fact does
68+
not matter to this task. It will take the provided inputs, organize them into
69+
the expected JSON file, and run Dackka with the JSON file as an argument.
70+
71+
### [FiresiteTransformTask]
72+
73+
Dackka was designed with Devsite in mind. The problem though, is that we use
74+
Firesite. Firesite is very similar to Devsite, but there *are* minor differences.
75+
76+
The job of this task is to transform the Dackka output from a Devsite purposed format,
77+
to a Firesite purposed format. This includes removing unnecessary files, fixing
78+
links, removing unnecessary headers, and so forth.
79+
80+
There are open bugs for each transformation, as in an ideal world- they are instead
81+
exposed as configurations from Dackka. Should these configurations be adopted by
82+
Dackka, this task could become unnecessary itself- as we could just configure the task
83+
during generation.
84+
85+
### DackkaPlugin
86+
87+
This plugin is the mind of our Dackka implementation. It manages registering,
88+
and configuring all the tasks for Dackka (that is, the already established
89+
tasks above). While we do not currently offer any configuration for the Dackka
90+
plugin, this could change in the future as needed. Currently, the DackkaPlugin
91+
provides sensible defaults to output directories, package lists, and so forth.
92+
93+
The DackkaPlugin also provides two extra tasks:
94+
[cleanDackkaDocumentation][registerCleanDackkaDocumentation] and
95+
[deleteDackkaGeneratedJavaReferences][registerDeleteDackkaGeneratedJavaReferencesTask].
96+
97+
_cleanDackkaDocumentation_ is exactly what it sounds like, a task to clean up (delete)
98+
the output of Dackka. This is useful when testing Dackka outputs itself- and
99+
shouldn't be apart of the normal flow. The reasoning is that it would otherwise
100+
invalidate the gradle cache.
101+
102+
_deleteDackkaGeneratedJavaReferences_ is a temporary addition. Dackka generates
103+
two separate styles of docs for every source set: Java & Kotlin. Regardless of
104+
whether the source is in Java or Kotlin. The Java output is how the source looks
105+
from Java, and the Kotlin output is how the source looks from Kotlin. We publish
106+
these under two separate categories, which you can see here:
107+
[Java](https://firebase.google.com/docs/reference/android/packages)
108+
or
109+
[Kotlin](https://firebase.google.com/docs/reference/kotlin/packages).
110+
Although, we do not currently publish Java packages with Dackka- and will wait
111+
until we are more comfortable with the output of Dackka to do so. So until then,
112+
this task will remove all generate Java references from the Dackka output.
113+
114+
Currently, the DackkaPlugin builds Java sources separate from Kotlin Sources. There is an open bug
115+
for Dackka in which hidden parent classes and annotations do not hide themselves from children classes.
116+
To work around this, we are currently generating stubs for Java sources via metalava, and feeding the stubs
117+
to Dackka. This will be removed when the bug is fixed, per b/243954517
29118
*/
30119
abstract class DackkaPlugin : Plugin<Project> {
31120
override fun apply(project: Project) {
@@ -70,7 +159,7 @@ abstract class DackkaPlugin : Plugin<Project> {
70159
)
71160
}
72161

73-
// TODO(b/243534168): Refactor when fixed, so we no longer need stubs
162+
// TODO(b/243324828): Refactor when fixed, so we no longer need stubs
74163
private fun registerGenerateDackkaDocumentationTask(project: Project): Provider<GenerateDocumentationTask> {
75164
val docStubs = project.tasks.register<GenerateStubsTask>("docStubsForDackkaInput")
76165
val docsTask = project.tasks.register<GenerateDocumentationTask>("generateDackkaDocumentation")

0 commit comments

Comments
 (0)