Building an Automated Documentation System with Toolips
Written on
Introduction to the Project
This year, I've dedicated a significant amount of time to organizing my software projects and expanding my capabilities. The goal is to deploy substantial personal projects from my home servers within the coming year. I'm pleased to report progress, having completed two ecosystems and nearing the finish of a third. However, there is one element I've delayed — creating a comprehensive documentation website utilizing Toolips for my chifi software.
While I could use that time on other tasks, developing this documentation site will simplify access to my software for a broader audience. It will also offer a platform for more extensive technical writing and examples related to the project. Today, I will outline my strategy for launching this initiative, dubbed ChifiDocs.
To kick off this project, we'll follow the conventional Toolips setup: generating an app with new_app, then incorporating ToolipsSession.
using Toolips
using Pkg; Pkg.add("ToolipsSession")
module ChifiDocs
using Toolips
using Toolips.Components
using ToolipsSession
# extensions
logger = Toolips.Logger()
session = Session(["/"])
...
export home, logger, session
end # ChifiDocs <3
Next, we'll focus on constructing a Julia-based back-end.
Backend Development
One of the key benefits of Toolips is that it integrates the back-end and front-end seamlessly. In many web development situations, the front-end and back-end communicate separately, but Toolips allows for direct interaction between them through registered callback events.
I envision several features for this documentation site. Firstly, I need an intuitive method for organizing my ecosystems and showcasing all packages and their contents. Additionally, I want to implement a tabbing feature, which will require storing inactive tabs either on the server or the client. Generally, the latter is preferred, but in this case, it makes more sense to retain the pages in memory since multiple clients access the same pages.
To establish a robust structure for our back-end, we'll create a DocModule and DocSystem to manage the data effectively.
mutable struct DocModule
mod::Module
pages::Vector{Component{<:Any}}
mdpath::String
end
mutable struct DocSystem
name::String
color::String
modules::Vector{DocModule}
end
These structures will support the DocModule which retains a Module, pages, and a markdown path. The DocSystem will encompass multiple DocModules, enhanced with categorical details like color and name.
Furthermore, we require a Toolips server extension to manage this data. Although we could use authenticated data from Auth, provided by ToolipsSession, I prefer to create a custom system for this purpose.
abstract type AbstractDocClient end
mutable struct DocClient <: AbstractDocClient
key::String
tabs::Vector{Component{<:Any}}
end
In this setup, we can define how to retrieve specific DocClient instances based on their keys.
getindex(dc::Vector{<:AbstractDocClient}, ref::String) = begin
pos = findfirst(cl::AbstractDocClient -> cl.key == ref, dc)
if isnothing(pos)
...end
dc[pos]::AbstractDocClient
end
Now, we will develop the front-end to complement this back-end, beginning with the construction of a menu from our modules.
function generate_menu(mods::Vector{DocSystem})
menuholder::Component{:div} = div("mainmenu", align = "center",
children = [begin
mdiv = a(string(menu_mod.name) * "eco", text = "$(menu_mod.name)")
style!(mdiv, "background-color" => menu_mod.color,
"color" => "white", "font-size" => 14pt, "padding" => 10px)
mdiv::Component{:a}
end for menu_mod in mods])
menuholder::Component{:div}
end
Video Guide: Ai Tool for Documentation - Scribe
This video explains how to use the Scribe tool for documentation generation, which aligns well with the goals of creating an automated documentation site.
Video Guide: Creating IT Documentation with ChatGPT
This video explores how to create IT documentation using ChatGPT, providing insights that can be beneficial for the development of ChifiDocs.
Continuing from where we left off, we’ll implement additional sub-elements to represent each package that will be displayed upon interaction with these elements.
function generate_tabbar(client::DocClient)
...
end
By organizing the front-end with a clear structure and responsive design, we can create an intuitive user experience.
Conclusion
The journey toward building an automated documentation system for both doc-strings and markdown is underway. We will continue to refine the back-end, update our data structures, and enhance the user interface. This ongoing project aims to provide comprehensive documentation that is both accessible and easy to navigate. Thank you for following along as I work to bring this vision to fruition!