diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/skribilo.scm | 105 | ||||
| -rw-r--r-- | doc/tissue.skb | 92 |
2 files changed, 197 insertions, 0 deletions
diff --git a/doc/skribilo.scm b/doc/skribilo.scm new file mode 100644 index 0000000..75ac3a2 --- /dev/null +++ b/doc/skribilo.scm @@ -0,0 +1,105 @@ +;;; tissue --- Text based issue tracker +;;; Copyright © 2022 Arun Isaac <arunisaac@systemreboot.net> +;;; +;;; This file is part of tissue. +;;; +;;; tissue is free software: you can redistribute it and/or modify it +;;; under the terms of the GNU General Public License as published by +;;; the Free Software Foundation, either version 3 of the License, or +;;; (at your option) any later version. +;;; +;;; tissue is distributed in the hope that it will be useful, but +;;; WITHOUT ANY WARRANTY; without even the implied warranty of +;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +;;; General Public License for more details. +;;; +;;; You should have received a copy of the GNU General Public License +;;; along with tissue. If not, see <https://www.gnu.org/licenses/>. + +(define-module (doc skribilo) + #:use-module (srfi srfi-1) + #:use-module (srfi srfi-9) + #:use-module (srfi srfi-26) + #:use-module (srfi srfi-171) + #:use-module (ice-9 match) + #:use-module (texinfo) + #:use-module (skribilo package base) + #:export (docstring-function-documentation + function-documentation)) + +(define-record-type <function> + (function name arguments docstring) + function? + (name function-name) + (arguments function-arguments) + (docstring function-docstring)) + +(define (find-function-definition file name) + "Return a @code{<function>} object describing a function named +@var{name} in @var{file}." + (call-with-input-file file + (cut port-transduce + (tmap identity) + (rany (match-lambda + (((or 'define 'define* 'define-lazy) + ((? (cut eq? name <>)) arguments ...) + docstring + body ...) + (function name arguments docstring)) + (_ #f))) + read + <>))) + +(define (stexi->skribe stexi) + "Convert @var{stexi}, a stexinfo tree, to a skribe tree." + (match stexi + (('*fragment* children ...) + (map stexi->skribe children)) + (('para children ...) + (cons 'paragraph children)))) + +(define (quoted-write object port) + "Write @var{object} to @var{port} printing quoted expressions using +the quote character." + (match object + (('quote child) + (display "'" port) + (quoted-write child port)) + ((parent children ...) + (display "(" port) + (quoted-write parent port) + (unless (null? children) + (display " " port)) + (for-each (cut quoted-write <> port) + children) + (display ")" port)) + (_ (write object port)))) + +(define (docstring-function-documentation file name) + "Document function of @var{name} from @var{file} using its docstring." + (let ((function (or (find-function-definition file name) + (error "Function not found in file:" name file)))) + (item #:key (code (list "(" + (bold (symbol->string name)) + (unless (null? (function-arguments function)) + " ") + (string-join (map (lambda (element) + (call-with-output-string + (cut quoted-write element <>))) + (function-arguments function))) + ")")) + (map (cut eval <> (current-module)) + (stexi->skribe + (texi-fragment->stexi + (function-docstring function))))))) + +(define (function-documentation name arguments . documentation) + "Document function of @var{name} with @var{arguments} and +@var{documentation}." + (apply item + #:key (code (list "(" + (bold (symbol->string name)) + " " + arguments + ")")) + documentation)) diff --git a/doc/tissue.skb b/doc/tissue.skb new file mode 100644 index 0000000..41159ae --- /dev/null +++ b/doc/tissue.skb @@ -0,0 +1,92 @@ +;;; tissue --- Text based issue tracker +;;; Copyright © 2022 Arun Isaac <arunisaac@systemreboot.net> +;;; +;;; This file is part of tissue. +;;; +;;; tissue is free software: you can redistribute it and/or modify it +;;; under the terms of the GNU General Public License as published by +;;; the Free Software Foundation, either version 3 of the License, or +;;; (at your option) any later version. +;;; +;;; tissue is distributed in the hope that it will be useful, but +;;; WITHOUT ANY WARRANTY; without even the implied warranty of +;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +;;; General Public License for more details. +;;; +;;; You should have received a copy of the GNU General Public License +;;; along with tissue. If not, see <https://www.gnu.org/licenses/>. + +(use-modules (doc skribilo)) + +(document :title [tissue] + (toc) + (chapter :title [Introduction] + (p [tissue is an issue tracker and project information management +system built on plain text files and git. It is specifically intended +for small free software projects. It features a static site generator +to build a project website and a powerful search interface to search +through project issues and documentation. The search interface is +built on the ,(ref :url "https://xapian.org/" :text "Xapian search +engine library"), and is available both as a command-line program and +as a web server.])) + (chapter :title [Gemtext markup for issues] + (p [Issues must be written in ,(ref +:url "https://gemini.circumlunar.space/docs/gemtext.gmi" +:text "gemtext markup") with added extra notation to specify issue +metadata.]) + (p [Tag issues.] + (prog :line #f + [* tags: enhancement, good first issue])) + (p [Close issues. Use either of] + (prog :line #f + [* closed]) + (prog :line #f + [* status: closed])) + (p [Assign issues to one or more people.] + (prog :line #f + [* assigned: mekalai]) + (prog :line #f + [* assigned: muthu, mekalai])) + (p [Create task lists with regular gemtext lists starting with +,(code "[ ]"). Tasks may be marked as completed by putting an +,(code "x") within the brackets, like so: ,(code "[x]")] + (prog :line #f + [* \[x\] Do this. +* \[ \] Then, do this. +* \[ \] Finally, do this.]))) + (chapter :title [Reference] + (section :title [Object and record constructors] + (description + (docstring-function-documentation "tissue/tissue.scm" 'tissue-configuration) + (function-documentation 'file [filename writer] + [Construct a ,(code [<file>]) object that represents an +output file to be created.] + (description + (item :key (var [filename]) + [the name of the file to create as a string]) + (item :key (var [writer]) + [a one-argument function that takes a port as an +argument and writes data destined for ,(var [filename]) into that +port]))))) + (section :title [Reader functions] + (p [These functions produce ,(code [<document>]) objects (or +objects of classes inheriting from ,(code [<document>])) by reading +files or other data sources.]) + (description + (docstring-function-documentation "tissue/issue.scm" 'read-gemtext-issue) + (docstring-function-documentation "tissue/file-document.scm" 'read-gemtext-document) + (docstring-function-documentation "tissue/commit.scm" 'commits-in-current-repository))) + (section :title [Writer functions] + [These functions write output files and are meant to be +specified in a ,(code [<file>]) object.] + (description + (docstring-function-documentation "tissue/web/static.scm" 'copier) + (docstring-function-documentation "tissue/web/static.scm" 'gemtext-exporter) + (docstring-function-documentation "tissue/web/static.scm" 'skribe-exporter))) + (section :title [Utility functions] + [These miscellaneous functions are useful when writing tissue +configuration files.] + (description + (docstring-function-documentation "tissue/tissue.scm" 'gemtext-files-in-directory) + (docstring-function-documentation "tissue/git.scm" 'git-tracked-files) + (docstring-function-documentation "tissue/document.scm" 'slot-set))))) |