summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorArun Isaac2022-10-10 00:56:55 +0530
committerArun Isaac2022-10-10 01:46:53 +0530
commit25c32afaeec73beee2616b9f8e613efbf95d4404 (patch)
treeaa788818c75c5bd0a06d92a0487924b6284d8c8d /doc
parent35c098803a217d29b0a69734ce38303a72be4084 (diff)
downloadtissue-25c32afaeec73beee2616b9f8e613efbf95d4404.tar.gz
tissue-25c32afaeec73beee2616b9f8e613efbf95d4404.tar.lz
tissue-25c32afaeec73beee2616b9f8e613efbf95d4404.zip
doc: Add documentation.
* doc/skribilo.scm, doc/tissue.skb: New files. * tissue.scm (#:web-files): Add manual/dev/en/index.html.
Diffstat (limited to 'doc')
-rw-r--r--doc/skribilo.scm105
-rw-r--r--doc/tissue.skb92
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)))))