Como gerar um diagrama wbs de seus projetos Android
Work breakdown structure (Wbs) ou Estrutura Analítica de Projetos é um modelo gráfico para representar projetos.
É sempre um prazer ter você por aqui, amigo leitor!
Hoje vamos continuar falando sobre estrutura de documentação eficaz para seus aplicativos, mas dessa vez vamos olhar um projeto android e como documenta-lo de forma dinâmica.
Se você não viu o meu artigo anterior sobre o tema, recomendo fortemente que acesse o texto. Uma introdução bem bacana sobre o tema.
Agora que você já olhou nosso texto anterior podemos avançar um pouco e falar especificamente sobre wbs (Work Breakdown Strucutre)
O Work Breakdown Structure (WBS) é um método de decomposição de trabalhos em partes menores e menos complexas. Ele é usado para ajudar a desenvolver uma ótima estrutura para um projeto e garantir que todas as tarefas sejam identificadas e gerenciadas adequadamente. O WBS pode ser usado para qualquer projeto, desde pequenos projetos de casa até grandes projetos corporativos. Ele fornece um meio para que os gerentes de projetos possam dividir seus trabalhos em partes menores, mais gerenciáveis, e garantir que cada tarefa seja realizada adequadamente.
Nosso objetivo com esse artigo é gerar uma documentação básica wbs para que seja possível demonstrar o estado atual do projeto android e seus principais módulos.
Para isso vamos utilizar um gradle plugin e uma task gradle que ficará responsável por ler o arquivo settings.xml e gerar nosso WBS.
Para fins de demonstração adicionei o nosso plugin no Projeto nowandroid um repositório mantido pela comunidade que tem muitos códigos com tudo que existe de mais atual no desenvolvimento mobile.
Now in Android App
Aplicativo foi projetado e construído no estudo de caso de design, jornada de aprendizado de arquitetura e jornada de aprendizado de modularização.
Now in Android é um aplicativo Android totalmente funcional construído inteiramente com Kotlin e Jetpack Compose. Ele segue as práticas recomendadas de design e desenvolvimento do Android e destina-se a ser uma referência útil para desenvolvedores. Como um aplicativo em execução, destina-se a ajudar os desenvolvedores a se manterem atualizados com o mundo do desenvolvimento Android, fornecendo atualizações regulares de notícias.
O aplicativo está atualmente em desenvolvimento. A variante demoRelease está disponível na Play Store em beta aberto.
Abaixo temos o fork do projeto nowandroid com a branch relacionada a esse artigo.
Fique a vontade para pegar o código funcional no repositório, de toda forma, vamos abordar o passo a passo para implementar a ferramenta.
Para concluir essa tarefa vou separar o processo em 3 partes, Gradle Task, Gradle Plugin e implementar o plugin no modulo App.
Gradle Task para salvar o arquivo wbs gerado pelo build.
open class DocsFileTask @Inject constructor(
@Input val stringToFile: String,
private val outputFile: File,
private val file: File,
) : DefaultTask() {
@TaskAction
fun execute() {
createResource(stringToFile)
}
private fun createResource(value: String) {
outputFile.mkdirs()
file.createNewFile()
file.writeText(value)
println("Result file path: ${file.toURL()}")
}
}Criamos a classe DocsFileTask com o objetivo de criar um arquivo após a compilação com a entrada string que representa nosso arquivo wbs puml.
Observe ainda que temos além do createResource a função execute com a annotation @TaskAction, sendo ela a responsável por registrar nossa gradle task.
Gradle Plugin e o processo de extração do Settings.gradle
Para essa etapa vamos precisar criar a classe DocumentationPlugin que tem uma herança com plugin<Project> dessa forma ela poderá ser incorporada ao processo de build e manipular a criação dos arquivos de compilação.
Mais sobre Plugins
APluginrepresents an extension to Gradle. A plugin applies some configuration to a target object. Usually, this target object is aProject, but plugins can be applied to any type of objects.
Observe nossa implementação na função apply.
class DocumentationPlugin : Plugin<Project> {
private val taskName = "DocsFileTask"
private val outputFilePath = "../reports"
override fun apply(target: Project) {
with(target) {
println("Project root dir: ${this.rootDir}")
val appModuleDocs = AppModuleDocs(this)
appModuleDocs.generateDocsWithSettingFile()
}
}
}
}Basicamente pegamos o projeto de destino e repassamos para a classe interna AppModuleDocs, após pré-processamento chamamos a função generateDocsWithSettingFile()
Na classe interna AppModuleDocs temos alguns métodos interessantes.
internal class AppModuleDocs(val project: Project) {
private val listOfUmlModel: MutableList<UmlModel> = mutableListOf()
fun generateDocsWithSettingFile() {
with(project) {
val settingsFile =
getSettingsOrNull(SETTINGS_GRADLE_KTS) ?: getSettingsOrNull(SETTINGS_GRADLE)
val builder = StringBuilder()
buildDiagramModel(settingsFile, builder)
createOutputUmlFile(builder)
println("Task Wbs settings.gradle included")
}
}A função generateDocsWithSettingFile é responsável por desencadear alguns processo como o buildDiagramModel e CreateOutputUmlFile
O buildDiagramModel processa o arquivo settings.gradle e armazena o mesmo em uma lista de dados por níveis de projeto e subprojeto.
private fun Project.buildDiagramModel(
settingsFile: File?,
builder: StringBuilder
) {
settingsFile?.let { file ->
val hashOfKeys = hashMapOf<String, List<String>>().toMutableMap()
extractSettingsFileToMap(file, hashOfKeys)
generateDiagramOutputString(builder, hashOfKeys)
}
}Já o CreateOutputUmlFile fica responsável por indicar o local do arquivo e desencadear a chamada da Gradle Task descrita na primeira etapa.
private fun Project.createOutputUmlFile(builder: StringBuilder) {
val file = project.file("$buildDir/reports-uml/settings.puml")
val fileDir = project.file("$buildDir/reports-uml")
createFileWithTask(project,
builder.toString(),
fileDir.absolutePath,
file.absolutePath
)
}Implementar o plugin no modulo app
Para implementar corretamente o plugin desenvolvido no segundo passo precisamos fazer algumas modificações no build.gradle.kts do modulo app.
Observe os trechos de código abaixo:
No submódulo build-logic/convetion precisamos adicionar o trecho de código a seguir.
register("documentation-plugin") {
id = "nowinandroid.documentation-plugin"
implementationClass = "DocumentationPlugin"
}No modulo app precisamos adicionar o trecho de código a seguir.
plugins {
...
id("nowinandroid.documentation-plugin")
}Observe que a seção plugins e register do arquivo gradle.kts são descritas com mais detalhes nos links;
De volta ao nosso exercício.
Com o o plugin configurado e devidamente registrado podemos realizar o sync do seu projeto.
Veja que no momento do build, aparecerá a mensagem “ Task Wbs Settings.gradle generated” conforme print configurado no nosso plugin.
Isso permitirá que você execute a gradle task “SettingsGradleWbs” e obtenha automaticamente um arquivo WBS do projeto.
Após o termino da compilação usando a task SettingsGradleWbs e acesse o arquivo gerado e tenha uma visualização do seu projeto :)
Por agora, isso é tudo pessoal.
