-(:packages :docgen :docgen-test :style-checker)
-(:name :docgen
+(:packages :sheep :sheep-test :wolf)
+(:name :sheep
:tasks
((:name :test :directions
- (docgen-test:run-all-tests))
- (:name :checkstyle :directions
- (syntax-checker:pretty-print-check-directory "src"))
- (:name :docgen :directions
- (docgen:pretty-print-validate-packages :docgen))))
+ (sheep-test:run-all-tests))
+ (:name :wolf :directions
+ (wolf:pretty-print-check-directory "src"))
+ (:name :sheep :directions
+ (sheep:pretty-print-validate-packages :sheep))))
; vim:ft=lisp
I wish I had aspirations for this being some standard that someone else might follow, but realistically I'm just irritated at my own laziness with regard to documentation, so I wrote a solution. The forceful nature of the validator is really just because I didn't want to write a smarter parser. As an added bonus, all the docs now look the same when I look at them in the repl, so that's kind of nice.
-If you like, you can [download it](https://github.com/frankduncan/docgen/releases/download/0.3/docgen_0.3.tar.gz)
+If you like, you can [download it](https://github.com/frankduncan/sheep/releases/download/0.3/sheep_0.3.tar.gz)
## Usage
-See the [wiki](https://github.com/frankduncan/docgen/wiki) for usage information (generated by this package).
+See the [wiki](https://github.com/frankduncan/sheep/wiki) for usage information (generated by this package).
To see how that page was created, take a look at bin/generatedocs.sh
#!/bin/bash
-version=$(sbcl --noinform --disable-ldb --lose-on-corruption --end-runtime-options --eval '(format t "~A" (asdf:component-version (asdf:find-system :docgen)))' --eval "(quit)")
+version=$(sbcl --noinform --disable-ldb --lose-on-corruption --end-runtime-options --eval '(format t "~A" (asdf:component-version (asdf:find-system :sheep)))' --eval "(quit)")
echo -n "Building version $version, hit enter to continue"
read
-mkdir docgen_$version
-cp -ap src/main/* docgen_$version/
-tar zcf docgen_${version}.tar.gz docgen_$version/
-rm -rf docgen_$version
+mkdir sheep_$version
+cp -ap src/main/* sheep_$version/
+tar zcf sheep_${version}.tar.gz sheep_$version/
+rm -rf sheep_$version
-echo "All done, it's in docgen_${version}.tar.gz, you should tag it and push it up to github"
+echo "All done, it's in sheep_${version}.tar.gz, you should tag it and push it up to github"
#!/bin/bash
sbcl \
- --eval "(asdf:load-system :docgen)" \
+ --eval "(asdf:load-system :sheep)" \
--eval "(format t \"----~%\")" \
- --eval "(format t \"~A\" (docgen:export-package :docgen))" \
+ --eval "(format t \"~A\" (sheep:export-package :sheep))" \
--eval "(quit)" 2> /dev/null | sed -n '/^----$/,$p' | tail -n +2 > wiki/Home.md
#!/bin/bash
sbcl \
- --eval "(asdf:load-system :docgen)" \
+ --eval "(asdf:load-system :sheep)" \
--eval "(load \"$1\")" \
--eval "(format t \"----~%\")" \
- --eval "(format t \"~A\" (docgen:export-package $2))" \
+ --eval "(format t \"~A\" (sheep:export-package $2))" \
--eval "(quit)" 2> /dev/null | sed -n '/^----$/,$p' | tail -n +2 > fromcl.md
vimdiff fromcl.md ${1/lisp/md}
+++ /dev/null
-(asdf:defsystem docgen
- :name "Documentation Generator"
- :version "0.3"
- :maintainer "Frank Duncan (frank@kank.com)"
- :author "Frank Duncan (frank@kank.com)"
- :serial t
- :components ((:file "package") (:file "func") (:file "var") (:file "pkg") (:file "struc") (:file "docgen"))
- :depends-on (:cl-ppcre))
+++ /dev/null
-(in-package #:docgen)
-
-(define-condition validation-failure nil ((msg :initarg :msg :reader validation-failure-msg))
- (:documentation "Used internally for docgen parts to signal a validation error."))
-
-(defun get-symb-type (symb)
- (cond
- ((documentation symb 'variable) :variable)
- ((documentation symb 'structure) :structure)
- ((documentation symb 'function) :function)))
-
-(defun validate-package (pkg)
- "VALIDATE-PACKAGE PKG => FAILURES
-
- FAILURES: FAILURE*
- FAILURE: (:failure SYMB MSG)
-
-ARGUMENTS AND VALUES:
-
- PKG: A package symbol
- SYMB: Symbol the check failed on
- MSG: Message containing information about the failure
-
-DESCRIPTION:
-
- VALIDATE-PACKAGE takes in PKG and validates that all the external symbols
- adhere to documentation guidelines, exist, and can be parsed to be used
- for exporting.
-
- Only one error per symbol will be reported at a time, all concatenated to
- a list in the aforementioned form."
- (macrolet
- ((with-success-check (symb &rest f)
- `(handler-case
- (progn ,@f :success)
- (validation-failure (v) (list :failure ,symb (validation-failure-msg v))))))
- (let
- ((symbs nil))
- (do-external-symbols (symb pkg) (push symb symbs))
- (setf symbs (sort symbs #'string< :key #'symbol-name))
- (remove :success
- (append
- (list (with-success-check pkg (docgen-pkg:doc->ast (find-package pkg))))
- (mapcar
- (lambda (symb)
- (with-success-check symb
- (case (get-symb-type symb)
- (:function (docgen-func:doc->ast symb))
- (:structure (docgen-struc:doc->ast symb))
- (:variable (docgen-var:doc->ast symb))
- (t (error (make-condition 'validation-failure :msg (format nil "Symbol ~A has no documentation" symb)))))))
- symbs))))))
-
-(defun pretty-print-validate-packages (&rest pkgs)
- "PRETTY-PRINT-VALIDATE-PACKAGES &rest PKGS => SUCCESS
-
- PKGS: PKG*
-
-ARGUMENTS AND VALUES:
-
- SUCCESS: Whether or not all symbols passed validation
- PKG: A package symbol
-
-DESCRIPTION:
-
- PRETTY-PRINT-VALIDATE-PACKAGES takes PKGS and runs validation on all of them.
- It dumps to standard out failures as it comes upon them, finally returning
- whether it was successful or not.
-
- This can be used in validation tests to ensure that documentation can be generated
- at a later date.
-
-EXAMPLES:
-
- (pretty-print-validate-packages :pkg1 :pkg2) => t"
- (every
- #'identity
- (mapcar
- (lambda (pkg)
- (let
- ((failures (validate-package pkg)))
- (mapcar
- (lambda (failure)
- (format t "In ~A : ~A, documentation error found:~% ~A~%" pkg (second failure) (third failure)))
- failures)
- (not failures)))
- pkgs)))
-
-(defun table-of-contents (pkg)
- (format nil "## Contents~%~%~{~{* **~A [~A](#~A)** - ~A~}~%~}"
- (let
- ((symbs nil))
- (do-external-symbols (symb pkg) (push symb symbs))
- (setf symbs (sort symbs #'string< :key #'symbol-name))
- (mapcar
- (lambda (symb)
- (case (get-symb-type symb)
- (:function
- (list
- (docgen-func:ast->category-name (docgen-func:doc->ast symb))
- (docgen-func:ast->short-name (docgen-func:doc->ast symb))
- (docgen-func:ast->link (docgen-func:doc->ast symb))
- (docgen-func:ast->short-desc (docgen-func:doc->ast symb))))
- (:structure
- (list
- (docgen-struc:ast->category-name (docgen-struc:doc->ast symb))
- (docgen-struc:ast->short-name (docgen-struc:doc->ast symb))
- (docgen-struc:ast->link (docgen-struc:doc->ast symb))
- (docgen-struc:ast->short-desc (docgen-struc:doc->ast symb))))
- (:variable
- (list
- (docgen-var:ast->category-name (docgen-var:doc->ast symb))
- (docgen-var:ast->short-name (docgen-var:doc->ast symb))
- (docgen-var:ast->link (docgen-var:doc->ast symb))
- (docgen-var:ast->short-desc (docgen-var:doc->ast symb))))))
- symbs))))
-
-(defun export-package (pkg)
- "EXPORT-PACKAGE PKG => MARKDOWN
-
-ARGUMENTS AND VALUES:
-
- PKG: A package symbol
- MARKDOWN: A string containing the markdown representation of this packages documentation
-
-DESCRIPTION:
-
- EXPORT-PACKAGE takes in PKG and converts all the documentation for the symbols
- into markdown with the hope of emulating the hyperspec style.
-
- It should only be run after the package has been validated, as it assumes that
- all documentation it gets will be valid."
- (let
- ((symbs nil))
- (do-external-symbols (symb pkg) (push symb symbs))
- (setf symbs (sort symbs #'string< :key #'symbol-name))
- (with-output-to-string (str)
- (format str "~A~%~%" (docgen-pkg:ast->md (docgen-pkg:doc->ast (find-package pkg))))
- (format str "~A~%" (table-of-contents pkg))
- (format str "~{~A~^~%~}"
- (mapcar
- (lambda (symb)
- (case (get-symb-type symb)
- (:variable (docgen-var:ast->md (docgen-var:doc->ast symb)))
- (:function (docgen-func:ast->md (docgen-func:doc->ast symb)))
- (:structure (docgen-struc:ast->md (docgen-struc:doc->ast symb)))))
- symbs)))))
-(in-package #:docgen-func)
+(in-package #:sheep-func)
(defvar *doc*)
(defvar *prev-line*)
(defun add-keyword (type)
(setf *keywords* (remove-duplicates (cons type *keywords*) :test #'string=)))
-(defun fire-error (msg) (error (make-instance 'docgen:validation-failure :msg msg)))
+(defun fire-error (msg) (error (make-instance 'sheep:validation-failure :msg msg)))
(defun expect-blank-line ()
(let
--- /dev/null
+(in-package #:sheep)
+
+(define-condition validation-failure nil ((msg :initarg :msg :reader validation-failure-msg))
+ (:documentation "Used internally for sheep parts to signal a validation error."))
+
+(defun get-symb-type (symb)
+ (cond
+ ((documentation symb 'variable) :variable)
+ ((documentation symb 'structure) :structure)
+ ((documentation symb 'function) :function)))
+
+(defun validate-package (pkg)
+ "VALIDATE-PACKAGE PKG => FAILURES
+
+ FAILURES: FAILURE*
+ FAILURE: (:failure SYMB MSG)
+
+ARGUMENTS AND VALUES:
+
+ PKG: A package symbol
+ SYMB: Symbol the check failed on
+ MSG: Message containing information about the failure
+
+DESCRIPTION:
+
+ VALIDATE-PACKAGE takes in PKG and validates that all the external symbols
+ adhere to documentation guidelines, exist, and can be parsed to be used
+ for exporting.
+
+ Only one error per symbol will be reported at a time, all concatenated to
+ a list in the aforementioned form."
+ (macrolet
+ ((with-success-check (symb &rest f)
+ `(handler-case
+ (progn ,@f :success)
+ (validation-failure (v) (list :failure ,symb (validation-failure-msg v))))))
+ (let
+ ((symbs nil))
+ (do-external-symbols (symb pkg) (push symb symbs))
+ (setf symbs (sort symbs #'string< :key #'symbol-name))
+ (remove :success
+ (append
+ (list (with-success-check pkg (sheep-pkg:doc->ast (find-package pkg))))
+ (mapcar
+ (lambda (symb)
+ (with-success-check symb
+ (case (get-symb-type symb)
+ (:function (sheep-func:doc->ast symb))
+ (:structure (sheep-struc:doc->ast symb))
+ (:variable (sheep-var:doc->ast symb))
+ (t (error (make-condition 'validation-failure :msg (format nil "Symbol ~A has no documentation" symb)))))))
+ symbs))))))
+
+(defun pretty-print-validate-packages (&rest pkgs)
+ "PRETTY-PRINT-VALIDATE-PACKAGES &rest PKGS => SUCCESS
+
+ PKGS: PKG*
+
+ARGUMENTS AND VALUES:
+
+ SUCCESS: Whether or not all symbols passed validation
+ PKG: A package symbol
+
+DESCRIPTION:
+
+ PRETTY-PRINT-VALIDATE-PACKAGES takes PKGS and runs validation on all of them.
+ It dumps to standard out failures as it comes upon them, finally returning
+ whether it was successful or not.
+
+ This can be used in validation tests to ensure that documentation can be generated
+ at a later date.
+
+EXAMPLES:
+
+ (pretty-print-validate-packages :pkg1 :pkg2) => t"
+ (every
+ #'identity
+ (mapcar
+ (lambda (pkg)
+ (let
+ ((failures (validate-package pkg)))
+ (mapcar
+ (lambda (failure)
+ (format t "In ~A : ~A, documentation error found:~% ~A~%" pkg (second failure) (third failure)))
+ failures)
+ (not failures)))
+ pkgs)))
+
+(defun table-of-contents (pkg)
+ (format nil "## Contents~%~%~{~{* **~A [~A](#~A)** - ~A~}~%~}"
+ (let
+ ((symbs nil))
+ (do-external-symbols (symb pkg) (push symb symbs))
+ (setf symbs (sort symbs #'string< :key #'symbol-name))
+ (mapcar
+ (lambda (symb)
+ (case (get-symb-type symb)
+ (:function
+ (list
+ (sheep-func:ast->category-name (sheep-func:doc->ast symb))
+ (sheep-func:ast->short-name (sheep-func:doc->ast symb))
+ (sheep-func:ast->link (sheep-func:doc->ast symb))
+ (sheep-func:ast->short-desc (sheep-func:doc->ast symb))))
+ (:structure
+ (list
+ (sheep-struc:ast->category-name (sheep-struc:doc->ast symb))
+ (sheep-struc:ast->short-name (sheep-struc:doc->ast symb))
+ (sheep-struc:ast->link (sheep-struc:doc->ast symb))
+ (sheep-struc:ast->short-desc (sheep-struc:doc->ast symb))))
+ (:variable
+ (list
+ (sheep-var:ast->category-name (sheep-var:doc->ast symb))
+ (sheep-var:ast->short-name (sheep-var:doc->ast symb))
+ (sheep-var:ast->link (sheep-var:doc->ast symb))
+ (sheep-var:ast->short-desc (sheep-var:doc->ast symb))))))
+ symbs))))
+
+(defun export-package (pkg)
+ "EXPORT-PACKAGE PKG => MARKDOWN
+
+ARGUMENTS AND VALUES:
+
+ PKG: A package symbol
+ MARKDOWN: A string containing the markdown representation of this packages documentation
+
+DESCRIPTION:
+
+ EXPORT-PACKAGE takes in PKG and converts all the documentation for the symbols
+ into markdown with the hope of emulating the hyperspec style.
+
+ It should only be run after the package has been validated, as it assumes that
+ all documentation it gets will be valid."
+ (let
+ ((symbs nil))
+ (do-external-symbols (symb pkg) (push symb symbs))
+ (setf symbs (sort symbs #'string< :key #'symbol-name))
+ (with-output-to-string (str)
+ (format str "~A~%~%" (sheep-pkg:ast->md (sheep-pkg:doc->ast (find-package pkg))))
+ (format str "~A~%" (table-of-contents pkg))
+ (format str "~{~A~^~%~}"
+ (mapcar
+ (lambda (symb)
+ (case (get-symb-type symb)
+ (:variable (sheep-var:ast->md (sheep-var:doc->ast symb)))
+ (:function (sheep-func:ast->md (sheep-func:doc->ast symb)))
+ (:structure (sheep-struc:ast->md (sheep-struc:doc->ast symb)))))
+ symbs)))))
-(defpackage #:docgen (:use :cl)
+(defpackage #:sheep (:use :cl)
(:export #:validate-package #:export-package #:validation-failure #:pretty-print-validate-packages)
- (:documentation "Main docgen package.
+ (:documentation "Main sheep package.
-Use docgen to validate that documentation strings on external symbols adhere to
+Use sheep to validate that documentation strings on external symbols adhere to
a strict format and exist, so that they can be output to markdown format, while
looking decent when used within a common lisp process."))
-(defpackage #:docgen-func (:use :cl)
+(defpackage #:sheep-func (:use :cl)
(:export #:doc->ast #:ast->md #:ast->link #:ast->short-name #:ast->short-desc #:ast->category-name))
-(defpackage #:docgen-var (:use :cl)
+(defpackage #:sheep-var (:use :cl)
(:export #:doc->ast #:ast->md #:ast->link #:ast->short-name #:ast->short-desc #:ast->category-name))
-(defpackage #:docgen-pkg (:use :cl)
+(defpackage #:sheep-pkg (:use :cl)
(:export #:doc->ast #:ast->md))
-(defpackage #:docgen-struc (:use :cl)
+(defpackage #:sheep-struc (:use :cl)
(:export #:doc->ast #:ast->md #:ast->link #:ast->short-name #:ast->short-desc #:ast->category-name))
-(in-package #:docgen-pkg)
+(in-package #:sheep-pkg)
-(defun fire-error (msg) (error (make-instance 'docgen:validation-failure :msg msg)))
+(defun fire-error (msg) (error (make-instance 'sheep:validation-failure :msg msg)))
(defun doc->ast (pkg)
(when (not (documentation pkg t)) (fire-error (format nil "Package ~A has no documentation" (package-name pkg))))
--- /dev/null
+(asdf:defsystem sheep
+ :name "Documentation Generator"
+ :version "0.3"
+ :maintainer "Frank Duncan (frank@consxy.com)"
+ :author "Frank Duncan (frank@consxy.com)"
+ :serial t
+ :components ((:file "package") (:file "func") (:file "var") (:file "pkg") (:file "struc") (:file "generate"))
+ :depends-on (:cl-ppcre))
-(in-package #:docgen-struc)
+(in-package #:sheep-struc)
-(defun fire-error (msg) (error (make-instance 'docgen:validation-failure :msg msg)))
+(defun fire-error (msg) (error (make-instance 'sheep:validation-failure :msg msg)))
(defun doc->ast (struc)
(labels
-(in-package #:docgen-var)
+(in-package #:sheep-var)
(defvar *doc*)
(defvar *prev-line*)
(defun add-keyword (type)
(setf *keywords* (remove-duplicates (cons type *keywords*) :test #'string=)))
-(defun fire-error (msg) (error (make-instance 'docgen:validation-failure :msg msg)))
+(defun fire-error (msg) (error (make-instance 'sheep:validation-failure :msg msg)))
(defun expect-blank-line ()
(let
+++ /dev/null
-(asdf:defsystem docgen-test
- :name "Document Generator Tests"
- :maintainer "Frank Duncan (frank@kank.com)"
- :author "Frank Duncan (frank@kank.com)"
- :serial t
- :components ((:file "package") (:file "main") (:file "failures"))
- :depends-on (:docgen))
-(in-package #:docgen-test)
+(in-package #:sheep-test)
(let
((long-line (format nil "~A~A"
-(in-package #:docgen-test)
+(in-package #:sheep-test)
(defvar *tests* nil)
(handler-case
(progn
(load ,source)
- (string= (slurp-file ,target) (docgen:export-package ,pkg)))
- (docgen:validation-failure (vf)
+ (string= (slurp-file ,target) (sheep:export-package ,pkg)))
+ (sheep:validation-failure (vf)
(format t "Validation failure gotten: ~A~%"
- (funcall (symbol-function (find-symbol "VALIDATION-FAILURE-MSG" :docgen)) vf)))))))
+ (funcall (symbol-function (find-symbol "VALIDATION-FAILURE-MSG" :sheep)) vf)))))))
(defmacro deffailuretest (pkg source expected)
`(deftest
(progn
(load ,source)
(let
- ((result (docgen:validate-package ,pkg)))
+ ((result (sheep:validate-package ,pkg)))
(or
(equal ,expected result)
(format t " Got error:~%~S~% but expected~%~S~%" result ,expected)))))))
(handler-case
(progn
(funcall
- (symbol-function (find-symbol "INTERNAL-DOC->AST" :docgen-func))
+ (symbol-function (find-symbol "INTERNAL-DOC->AST" :sheep-func))
'unused
,doc)
nil)
- (docgen:validation-failure (vf)
+ (sheep:validation-failure (vf)
(let
- ((result (funcall (symbol-function (find-symbol "VALIDATION-FAILURE-MSG" :docgen)) vf)))
+ ((result (funcall (symbol-function (find-symbol "VALIDATION-FAILURE-MSG" :sheep)) vf)))
(or
(string= ,expected result)
(format t " Got error:~%~S~% but expected~%~S~%" result ,expected))))))))
(handler-case
(progn
(funcall
- (symbol-function (find-symbol "INTERNAL-DOC->AST" :docgen-var))
+ (symbol-function (find-symbol "INTERNAL-DOC->AST" :sheep-var))
'*unused*
,doc)
nil)
- (docgen:validation-failure (vf)
+ (sheep:validation-failure (vf)
(let
- ((result (funcall (symbol-function (find-symbol "VALIDATION-FAILURE-MSG" :docgen)) vf)))
+ ((result (funcall (symbol-function (find-symbol "VALIDATION-FAILURE-MSG" :sheep)) vf)))
(or
(string= ,expected result)
(format t " Got error:~%~S~% but expected~%~S~%" result ,expected))))))))
-(defpackage #:docgen-test (:use :common-lisp)
+(defpackage #:sheep-test (:use :common-lisp)
(:export :run-all-tests))
--- /dev/null
+(asdf:defsystem sheep-test
+ :name "Sheep Tests"
+ :maintainer "Frank Duncan (frank@consxy.com)"
+ :author "Frank Duncan (frank@consxy.com)"
+ :serial t
+ :components ((:file "package") (:file "main") (:file "failures"))
+ :depends-on (:sheep))
projects / sheep / commitdiff