From 71f49993d7ef1290feb22e882119285f8790d110 Mon Sep 17 00:00:00 2001 From: aleteoryx Date: Sun, 10 Nov 2024 18:15:17 -0500 Subject: [PATCH] docs generation --- bin/docextract.tcl | 72 +++++++++++++++++++++++++++++++ bin/docgen.tcl | 52 ++++++++++++++++++++++ doc/doctools/gen/cap.man | 5 +++ doc/doctools/gen/db/main.man | 5 +++ doc/doctools/gen/irc.man | 5 +++ doc/doctools/gen/irc/main.man | 5 +++ doc/doctools/gen/main.man | 5 +++ doc/doctools/gen/migrate_core.man | 5 +++ doc/doctools/gen/plugins.man | 5 +++ doc/doctools/gen/spdx/lib.man | 5 +++ doc/doctools/gen/threads.man | 5 +++ doc/doctools/gen/ui/main.man | 5 +++ doc/md/cap.md | 16 +++++++ doc/md/db/main.md | 16 +++++++ doc/md/irc.md | 16 +++++++ doc/md/irc/main.md | 16 +++++++ doc/md/main.md | 16 +++++++ doc/md/migrate_core.md | 16 +++++++ doc/md/plugins.md | 16 +++++++ doc/md/spdx/lib.md | 16 +++++++ doc/md/threads.md | 16 +++++++ doc/md/ui/main.md | 16 +++++++ src/cap.tcl | 9 ++++ src/db/main.tcl | 8 ++++ src/irc.tcl | 8 +++- src/irc/main.tcl | 7 +++ src/main.tcl | 8 ++++ src/migrate_core.tcl | 8 ++++ src/plugins.tcl | 8 ++++ src/spdx/lib.tcl | 8 ++++ src/threads.tcl | 8 ++++ src/ui/main.tcl | 8 ++++ 32 files changed, 413 insertions(+), 1 deletion(-) create mode 100755 bin/docextract.tcl create mode 100755 bin/docgen.tcl create mode 100644 doc/doctools/gen/cap.man create mode 100644 doc/doctools/gen/db/main.man create mode 100644 doc/doctools/gen/irc.man create mode 100644 doc/doctools/gen/irc/main.man create mode 100644 doc/doctools/gen/main.man create mode 100644 doc/doctools/gen/migrate_core.man create mode 100644 doc/doctools/gen/plugins.man create mode 100644 doc/doctools/gen/spdx/lib.man create mode 100644 doc/doctools/gen/threads.man create mode 100644 doc/doctools/gen/ui/main.man create mode 100644 doc/md/cap.md create mode 100644 doc/md/db/main.md create mode 100644 doc/md/irc.md create mode 100644 doc/md/irc/main.md create mode 100644 doc/md/main.md create mode 100644 doc/md/migrate_core.md create mode 100644 doc/md/plugins.md create mode 100644 doc/md/spdx/lib.md create mode 100644 doc/md/threads.md create mode 100644 doc/md/ui/main.md diff --git a/bin/docextract.tcl b/bin/docextract.tcl new file mode 100755 index 0000000..8ae42d9 --- /dev/null +++ b/bin/docextract.tcl @@ -0,0 +1,72 @@ +#!/bin/sh +# -*- tcl -*- +# The next line is executed by /bin/sh, but not tcl \ +exec tclsh "$0" ${1+"$@"} + +# taken from +# https://github.com/jcowgar/misctcl/blob/master/docextract.tcl + +package require cmdline + +proc main {} { + if {[llength $::argv] == 0} { + puts "Invalid usage, please use -help for help." + exit 0 + } + + set options { + {o.arg "./" "set the output directory"} + {ext.arg "man" "set the extension of the extracted document files"} + {doctools.arg no "generate HTML output via doctools package"} + {all "output output even when no valid comments where found"} + } + + set usage "\[options] filename1 \[filename2] \[...]\noptions:" + if {[catch {array set params [::cmdline::getoptions ::argv $options $usage]} msg]} { + puts $msg + exit 0 + } + + if {$params(doctools)} { + package require doctools + } + + file mkdir $params(o) + + foreach fname $::argv { + set fh [open $fname r] + set comments "" + + set inDocComment 0 + + while {[gets $fh line] >=0} { + set line [string trim $line] + if {$inDocComment && [string index $line 0] != "#"} { + set inDocComment 0 + } elseif {[string range $line 0 1]=="#*"} { + set inDocComment 1 + } elseif {$inDocComment} { + append comments "[string range $line 2 end]\n" + } + } + + close $fh + + if {$params(all) || [string length $comments] > 0} { + set ofh [open [file join $params(o) [file rootname $fname].$params(ext)] w] + puts $ofh $comments + close $ofh + + if {$params(doctools)} { + ::doctools::new .dt -format html + set html [.dt format $comments] + + set ofh [open [file join $params(o) [file rootname $fname].html] w] + puts $ofh $html + close $ofh + } + } + } +} + +main diff --git a/bin/docgen.tcl b/bin/docgen.tcl new file mode 100755 index 0000000..c78d251 --- /dev/null +++ b/bin/docgen.tcl @@ -0,0 +1,52 @@ +#!/bin/env tclsh + +set files { + *.tcl + spdx/lib.tcl + ui/*.tcl + db/*.tcl + irc/*.tcl +} + +set basedir \ + [file normalize \ + [file join \ + [file dirname \ + [dict get [info frame [info frame]] file]] ..]] + +cd [file join $basedir src] + +set files [glob -nocomplain {*}$files] + +file mkdir [file join $basedir doc doctools gen] +exec -- [file join $basedir bin docextract.tcl] -o [file join $basedir doc doctools gen] -all {*}$files + +package require doctools +doctools::new .doc +.doc configure -format markdown -ibase [file join $basedir doc doctools] + +cd [file join $basedir doc doctools gen] + +set to_check . +while {[llength $to_check]} { + set to_check [lassign $to_check cur] + foreach file [glob -directory $cur -types f -nocomplain *.man] { + set ofile [file rootname $file].md + set opath [file join $basedir doc md $ofile] + file mkdir [file dirname $opath] + + .doc configure -file $ofile + + set ifd [open $file r] + set ofd [open $opath w] + puts -nonewline $ofd [.doc format [read $ifd]] + close $ifd + close $ofd + + # TODO: postprocess to remove toc + + puts $ofile + } + + lappend to_check {*}[glob -directory $cur -types d -nocomplain *] +} diff --git a/doc/doctools/gen/cap.man b/doc/doctools/gen/cap.man new file mode 100644 index 0000000..44d387f --- /dev/null +++ b/doc/doctools/gen/cap.man @@ -0,0 +1,5 @@ +[manpage_begin cap tclircc 0.0.1] +[titledesc {Library cap.tcl}] +[description] +[manpage_end] + diff --git a/doc/doctools/gen/db/main.man b/doc/doctools/gen/db/main.man new file mode 100644 index 0000000..582657a --- /dev/null +++ b/doc/doctools/gen/db/main.man @@ -0,0 +1,5 @@ +[manpage_begin db_thread tclircc 0.0.1] +[titledesc {Thread tclircc::db}] +[description] +[manpage_end] + diff --git a/doc/doctools/gen/irc.man b/doc/doctools/gen/irc.man new file mode 100644 index 0000000..d31004e --- /dev/null +++ b/doc/doctools/gen/irc.man @@ -0,0 +1,5 @@ +[manpage_begin irc tclircc 0.0.1] +[titledesc {Library irc.tcl}] +[description] +[manpage_end] + diff --git a/doc/doctools/gen/irc/main.man b/doc/doctools/gen/irc/main.man new file mode 100644 index 0000000..53ce4ee --- /dev/null +++ b/doc/doctools/gen/irc/main.man @@ -0,0 +1,5 @@ +[manpage_begin irc_thread tclircc 0.0.1] +[titledesc {Thread tclircc::irc}] +[description] +[manpage_end] + diff --git a/doc/doctools/gen/main.man b/doc/doctools/gen/main.man new file mode 100644 index 0000000..6f177ff --- /dev/null +++ b/doc/doctools/gen/main.man @@ -0,0 +1,5 @@ +[manpage_begin main_thread tclircc 0.0.1] +[titledesc {Thread main}] +[description] +[manpage_end] + diff --git a/doc/doctools/gen/migrate_core.man b/doc/doctools/gen/migrate_core.man new file mode 100644 index 0000000..cd31fab --- /dev/null +++ b/doc/doctools/gen/migrate_core.man @@ -0,0 +1,5 @@ +[manpage_begin migrate_core tclircc 0.0.1] +[titledesc {Script migrate_core.tcl}] +[description] +[manpage_end] + diff --git a/doc/doctools/gen/plugins.man b/doc/doctools/gen/plugins.man new file mode 100644 index 0000000..ebc0c67 --- /dev/null +++ b/doc/doctools/gen/plugins.man @@ -0,0 +1,5 @@ +[manpage_begin plugins tclircc 0.0.1] +[titledesc {Component plugins.tcl}] +[description] +[manpage_end] + diff --git a/doc/doctools/gen/spdx/lib.man b/doc/doctools/gen/spdx/lib.man new file mode 100644 index 0000000..f61e9a3 --- /dev/null +++ b/doc/doctools/gen/spdx/lib.man @@ -0,0 +1,5 @@ +[manpage_begin spdx tclircc 0.0.1] +[titledesc {Library spdx/lib.tcl}] +[description] +[manpage_end] + diff --git a/doc/doctools/gen/threads.man b/doc/doctools/gen/threads.man new file mode 100644 index 0000000..e834b5c --- /dev/null +++ b/doc/doctools/gen/threads.man @@ -0,0 +1,5 @@ +[manpage_begin threads tclircc 0.0.1] +[titledesc {Component threads.tcl}] +[description] +[manpage_end] + diff --git a/doc/doctools/gen/ui/main.man b/doc/doctools/gen/ui/main.man new file mode 100644 index 0000000..1b90060 --- /dev/null +++ b/doc/doctools/gen/ui/main.man @@ -0,0 +1,5 @@ +[manpage_begin ui_thread tclircc 0.0.1] +[titledesc {Thread tclircc::ui}] +[description] +[manpage_end] + diff --git a/doc/md/cap.md b/doc/md/cap.md new file mode 100644 index 0000000..17f5526 --- /dev/null +++ b/doc/md/cap.md @@ -0,0 +1,16 @@ + +[//000000001]: # (cap \- ) +[//000000002]: # (Generated from file 'doctools' by tcllib/doctools with format 'markdown') +[//000000003]: # (cap\(tclircc\) 0\.0\.1 "") + +# NAME + +cap \- Library cap\.tcl + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Description](#section1) + +# DESCRIPTION diff --git a/doc/md/db/main.md b/doc/md/db/main.md new file mode 100644 index 0000000..33ffd01 --- /dev/null +++ b/doc/md/db/main.md @@ -0,0 +1,16 @@ + +[//000000001]: # (db\_thread \- ) +[//000000002]: # (Generated from file 'doctools' by tcllib/doctools with format 'markdown') +[//000000003]: # (db\_thread\(tclircc\) 0\.0\.1 "") + +# NAME + +db\_thread \- Thread tclircc::db + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Description](#section1) + +# DESCRIPTION diff --git a/doc/md/irc.md b/doc/md/irc.md new file mode 100644 index 0000000..4eeb3ee --- /dev/null +++ b/doc/md/irc.md @@ -0,0 +1,16 @@ + +[//000000001]: # (irc \- ) +[//000000002]: # (Generated from file 'doctools' by tcllib/doctools with format 'markdown') +[//000000003]: # (irc\(tclircc\) 0\.0\.1 "") + +# NAME + +irc \- Library irc\.tcl + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Description](#section1) + +# DESCRIPTION diff --git a/doc/md/irc/main.md b/doc/md/irc/main.md new file mode 100644 index 0000000..476bb61 --- /dev/null +++ b/doc/md/irc/main.md @@ -0,0 +1,16 @@ + +[//000000001]: # (irc\_thread \- ) +[//000000002]: # (Generated from file 'doctools' by tcllib/doctools with format 'markdown') +[//000000003]: # (irc\_thread\(tclircc\) 0\.0\.1 "") + +# NAME + +irc\_thread \- Thread tclircc::irc + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Description](#section1) + +# DESCRIPTION diff --git a/doc/md/main.md b/doc/md/main.md new file mode 100644 index 0000000..0e2e16f --- /dev/null +++ b/doc/md/main.md @@ -0,0 +1,16 @@ + +[//000000001]: # (main\_thread \- ) +[//000000002]: # (Generated from file 'doctools' by tcllib/doctools with format 'markdown') +[//000000003]: # (main\_thread\(tclircc\) 0\.0\.1 "") + +# NAME + +main\_thread \- Thread main + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Description](#section1) + +# DESCRIPTION diff --git a/doc/md/migrate_core.md b/doc/md/migrate_core.md new file mode 100644 index 0000000..2a21269 --- /dev/null +++ b/doc/md/migrate_core.md @@ -0,0 +1,16 @@ + +[//000000001]: # (migrate\_core \- ) +[//000000002]: # (Generated from file 'doctools' by tcllib/doctools with format 'markdown') +[//000000003]: # (migrate\_core\(tclircc\) 0\.0\.1 "") + +# NAME + +migrate\_core \- Script migrate\_core\.tcl + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Description](#section1) + +# DESCRIPTION diff --git a/doc/md/plugins.md b/doc/md/plugins.md new file mode 100644 index 0000000..a923d52 --- /dev/null +++ b/doc/md/plugins.md @@ -0,0 +1,16 @@ + +[//000000001]: # (plugins \- ) +[//000000002]: # (Generated from file 'doctools' by tcllib/doctools with format 'markdown') +[//000000003]: # (plugins\(tclircc\) 0\.0\.1 "") + +# NAME + +plugins \- Component plugins\.tcl + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Description](#section1) + +# DESCRIPTION diff --git a/doc/md/spdx/lib.md b/doc/md/spdx/lib.md new file mode 100644 index 0000000..f936ad6 --- /dev/null +++ b/doc/md/spdx/lib.md @@ -0,0 +1,16 @@ + +[//000000001]: # (spdx \- ) +[//000000002]: # (Generated from file 'doctools' by tcllib/doctools with format 'markdown') +[//000000003]: # (spdx\(tclircc\) 0\.0\.1 "") + +# NAME + +spdx \- Library spdx/lib\.tcl + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Description](#section1) + +# DESCRIPTION diff --git a/doc/md/threads.md b/doc/md/threads.md new file mode 100644 index 0000000..57505f5 --- /dev/null +++ b/doc/md/threads.md @@ -0,0 +1,16 @@ + +[//000000001]: # (threads \- ) +[//000000002]: # (Generated from file 'doctools' by tcllib/doctools with format 'markdown') +[//000000003]: # (threads\(tclircc\) 0\.0\.1 "") + +# NAME + +threads \- Component threads\.tcl + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Description](#section1) + +# DESCRIPTION diff --git a/doc/md/ui/main.md b/doc/md/ui/main.md new file mode 100644 index 0000000..9241d07 --- /dev/null +++ b/doc/md/ui/main.md @@ -0,0 +1,16 @@ + +[//000000001]: # (ui\_thread \- ) +[//000000002]: # (Generated from file 'doctools' by tcllib/doctools with format 'markdown') +[//000000003]: # (ui\_thread\(tclircc\) 0\.0\.1 "") + +# NAME + +ui\_thread \- Thread tclircc::ui + +# Table Of Contents + + - [Table Of Contents](#toc) + + - [Description](#section1) + +# DESCRIPTION diff --git a/src/cap.tcl b/src/cap.tcl index fb03c8a..0910013 100644 --- a/src/cap.tcl +++ b/src/cap.tcl @@ -1,3 +1,9 @@ +#*** +# [manpage_begin cap tclircc 0.0.1] +# [titledesc {Library cap.tcl}] +# [description] + + # cap.status: # - sent (we have sent CAP LS 302, no terminal reply) # - ack-wait (we've sent off the first REQ, wait for an ACK to update state and send END. will only transition when cap.req-inflight == {}) @@ -314,3 +320,6 @@ namespace eval ::cap { irc::msg send $chan CAP LS 302 } } + +#*** +# [manpage_end] diff --git a/src/db/main.tcl b/src/db/main.tcl index fe14208..8af4246 100644 --- a/src/db/main.tcl +++ b/src/db/main.tcl @@ -1,3 +1,8 @@ +#*** +# [manpage_begin db_thread tclircc 0.0.1] +# [titledesc {Thread tclircc::db}] +# [description] + package require sqlite3 package require logger @@ -36,3 +41,6 @@ proc backup {} { ${log}::info "backup to $backup_dir complete!" return $backup_dir } + +#*** +# [manpage_end] diff --git a/src/irc.tcl b/src/irc.tcl index 7e44281..495c66d 100644 --- a/src/irc.tcl +++ b/src/irc.tcl @@ -1,4 +1,7 @@ -#!/bin/tclsh +#*** +# [manpage_begin irc tclircc 0.0.1] +# [titledesc {Library irc.tcl}] +# [description] # handler types: # chan // irc::listener @@ -814,3 +817,6 @@ namespace eval ::irc { } } } + +#*** +# [manpage_end] diff --git a/src/irc/main.tcl b/src/irc/main.tcl index ae44443..ace499d 100644 --- a/src/irc/main.tcl +++ b/src/irc/main.tcl @@ -1,5 +1,12 @@ +#*** +# [manpage_begin irc_thread tclircc 0.0.1] +# [titledesc {Thread tclircc::irc}] +# [description] + package require logger source [file join $path irc.tcl] source [file join $path cap.tcl] +#*** +# [manpage_end] diff --git a/src/main.tcl b/src/main.tcl index 174615b..78e60e9 100755 --- a/src/main.tcl +++ b/src/main.tcl @@ -1,5 +1,10 @@ #!/bin/env tclsh +#*** +# [manpage_begin main_thread tclircc 0.0.1] +# [titledesc {Thread main}] +# [description] + set path [file dirname [dict get [info frame 0] file]] set version v0.0.1 proc src {file} { @@ -66,3 +71,6 @@ t::exec tclircc::ui { ${log}::info "entering event loop" vwait nil + +#*** +# [manpage_end] diff --git a/src/migrate_core.tcl b/src/migrate_core.tcl index d4e110d..dda4a3d 100644 --- a/src/migrate_core.tcl +++ b/src/migrate_core.tcl @@ -1,3 +1,8 @@ +#*** +# [manpage_begin migrate_core tclircc 0.0.1] +# [titledesc {Script migrate_core.tcl}] +# [description] + # TODO: make this more robust maybe interp create migrator @@ -49,3 +54,6 @@ migrator eval { ${log}::info "core db migrated!" } interp delete migrator + +#*** +# [manpage_end] diff --git a/src/plugins.tcl b/src/plugins.tcl index bcb325f..dc2839a 100644 --- a/src/plugins.tcl +++ b/src/plugins.tcl @@ -1,3 +1,8 @@ +#*** +# [manpage_begin plugins tclircc 0.0.1] +# [titledesc {Component plugins.tcl}] +# [description] + package require sha256 # plugin manifest format: @@ -338,3 +343,6 @@ namespace eval plugins { } } + +#*** +# [manpage_end] diff --git a/src/spdx/lib.tcl b/src/spdx/lib.tcl index 677db59..4aed453 100644 --- a/src/spdx/lib.tcl +++ b/src/spdx/lib.tcl @@ -1,3 +1,8 @@ +#*** +# [manpage_begin spdx tclircc 0.0.1] +# [titledesc {Library spdx/lib.tcl}] +# [description] + namespace eval spdx { set log [logger::init spdx] @@ -56,3 +61,6 @@ namespace eval spdx { dict get [set db($id)] see_also } } + +#*** +# [manpage_end] diff --git a/src/threads.tcl b/src/threads.tcl index 67b1f1c..e3a29bc 100644 --- a/src/threads.tcl +++ b/src/threads.tcl @@ -1,3 +1,8 @@ +#*** +# [manpage_begin threads tclircc 0.0.1] +# [titledesc {Component threads.tcl}] +# [description] + namespace eval threads { variable threads [list main [thread::id]] variable log [logger::init tclircc::threads] @@ -105,3 +110,6 @@ namespace eval threads { ::update } } + +#*** +# [manpage_end] diff --git a/src/ui/main.tcl b/src/ui/main.tcl index 5fd30da..cd459c2 100644 --- a/src/ui/main.tcl +++ b/src/ui/main.tcl @@ -1,3 +1,8 @@ +#*** +# [manpage_begin ui_thread tclircc 0.0.1] +# [titledesc {Thread tclircc::ui}] +# [description] + variable toplevel_count 0 variable toplevel_tabs variable toplevel_classes @@ -65,3 +70,6 @@ proc mk_toplevel {varname {takefocus 0}} { } ${log}::debug "ui init done!" + +#*** +# [manpage_end] -- 2.45.2