From: Frank Duncan Date: Thu, 13 Aug 2015 12:14:15 +0000 (-0500) Subject: Add documentation and docgen X-Git-Url: https://code.consxy.com/gitweb/gitweb.cgi?a=commitdiff_plain;h=8c769fe7229a74e60b03db471c98b5e8955a0f5c;p=wolf Add documentation and docgen --- diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..e90c9cf --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "wiki"] + path = wiki + url = https://github.com/frankduncan/style-checker.wiki.git diff --git a/.travis.yml b/.travis.yml index e7fc066..368439f 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,5 +1,5 @@ before_install: - - wget http://frank.kank.net/travissbcl/style-checker/ef9a5c7/$(git rev-parse HEAD)/travissbcl + - wget http://frank.kank.net/travissbcl/style-checker/79f4f3d/$(git rev-parse HEAD)/travissbcl - chmod +x travissbcl script: diff --git a/README.md b/README.md index 290c324..209be70 100644 --- a/README.md +++ b/README.md @@ -27,10 +27,6 @@ If you like, you can [download it](https://github.com/frankduncan/style-checker/ ## Usage -``` -(check-file file) +See the [wiki](https://github.com/frankduncan/style-checker/wiki). -(check-directory dir) - -(check-directory pretty-print-check-directory) -``` +Also, see bin/travis.lisp to see how it's used in this package. diff --git a/bin/buildtravisexec.sh b/bin/buildtravisexec.sh index 20480da..6229432 100755 --- a/bin/buildtravisexec.sh +++ b/bin/buildtravisexec.sh @@ -12,7 +12,9 @@ mkdir -p tmp/deps/ ( cd tmp/deps && tar zxf ../../deps/tarpit/cl-ppcre.tar.gz && - ln -s cl-ppcre-2.0.10/cl-ppcre.asd . + tar zxf ../../deps/tarpit/docgen_0.1.tar.gz && + ln -s cl-ppcre-2.0.10/cl-ppcre.asd . && + ln -s docgen_0.1/docgen.asd . ) @@ -20,6 +22,7 @@ SBCL_HOME="" tmp/sbcl/bin/sbcl --core tmp/sbcl/lib/sbcl/sbcl.core --no-sysinit - --eval "(require 'asdf)" \ --eval '(setf asdf:*central-registry* (list #p"tmp/deps/"))' \ --eval "(asdf:load-system :cl-ppcre)" \ + --eval "(asdf:load-system :docgen)" \ --eval "(asdf:clear-output-translations)" \ --eval '(sb-ext:save-lisp-and-die "travissbcl" :executable t)' \ diff --git a/bin/generatedocs.sh b/bin/generatedocs.sh new file mode 100755 index 0000000..25af9b8 --- /dev/null +++ b/bin/generatedocs.sh @@ -0,0 +1,8 @@ +#!/bin/bash + +sbcl \ + --eval "(asdf:load-system :docgen)" \ + --eval "(asdf:load-system :style-checker)" \ + --eval "(format t \"----~%\")" \ + --eval "(format t \"~A\" (docgen:export-package :syntax-checker))" \ + --eval "(quit)" 2> /dev/null | sed -n '/^----$/,$p' | tail -n +2 > wiki/Home.md diff --git a/bin/travis.lisp b/bin/travis.lisp index 4892120..17e87e1 100644 --- a/bin/travis.lisp +++ b/bin/travis.lisp @@ -13,6 +13,13 @@ (when (not (syntax-checker:pretty-print-check-directory "src")) (format t "~c[1;31mFailed style check!~c[0m~%" #\Esc #\Esc) (sb-ext:exit :code 1)) +(format t "~c[1;32m- Style Passed!~c[0m~%" #\Esc #\Esc) + +(format t "~%~c[1;33mChecking Docs~c[0m~%" #\Esc #\Esc) +(when (not (docgen:pretty-print-validate-packages :docgen)) + (format t "~c[1;31mFailed doc check!~c[0m~%" #\Esc #\Esc) + (sb-ext:exit :code 1)) +(format t "~c[1;32m- Doc Check Passed!~c[0m~%" #\Esc #\Esc) (format t "~c[1;32mSuccess!~c[0m~%" #\Esc #\Esc) (sb-ext:exit :code 0) diff --git a/deps/tarpit/docgen_0.1.tar.gz b/deps/tarpit/docgen_0.1.tar.gz new file mode 100644 index 0000000..bad2c6e Binary files /dev/null and b/deps/tarpit/docgen_0.1.tar.gz differ diff --git a/src/main/package.lisp b/src/main/package.lisp index 31eb3e3..504f2ac 100644 --- a/src/main/package.lisp +++ b/src/main/package.lisp @@ -1,2 +1,9 @@ (defpackage #:syntax-checker (:use :cl) - (:export #:check-file #:check-directory #:pretty-print-check-directory)) + (:export #:check-file #:check-directory #:pretty-print-check-directory) + (:documentation + "Enforces arbitrary set of style guidelines. + +This package walks over common lisp code to make sure it adheres to a set +of syntactic guidelines designed to ensure a semblance of uniformity. No +current one was found that could be configured to work the way this one does, +so instead of writing a configurable tool, another unconfigurable one was born.")) diff --git a/src/main/syntax-checker.lisp b/src/main/syntax-checker.lisp index 79cf0f5..f6c31da 100644 --- a/src/main/syntax-checker.lisp +++ b/src/main/syntax-checker.lisp @@ -93,7 +93,7 @@ SUCCESS-RESULT: (:success FILENAME) FAILURE-RESULT: (:success FILENAME MSG LINE-NO COL-NO) -ARGUMENTS AND VALUES +ARGUMENTS AND VALUES: FILE: a pathname FILENAME: the file this check was run on @@ -126,6 +126,23 @@ EXAMPLES: (list :failure file (check-failure-msg cf) (check-failure-line-no cf) (check-failure-col-no cf))))) (defun check-directory (dir) + "CHECK-DIRECTORY DIR => RESULTS + + RESULTS: RESULT* + +ARGUMENTS AND VALUES: + + DIR: A directory to recurse into and check files + RESULT: A result as returned by check-file + +DESCRIPTION: + + CHECK-DIRECTORY grabs all .lisp files in the tree under DIR, and loads + checks them all. + + The results are then put together into a list which can be programatically + evaluated. As opposed to pretty-print-check-directory, this function doesn't + clutter up your standard out." (mapcar #'check-file (directory (format nil "~A/**/*.lisp" dir)))) (defun any-failures (checks) @@ -142,6 +159,24 @@ EXAMPLES: (+ (fifth failure) 2))) (defun pretty-print-check-directory (dir) + "PRETTY-PRINT-CHECK-DIRECTORY DIR => SUCCESS + +ARGUMENTS AND VALUES: + + DIR: A directory to recurse into and check files + SUCCESS: T if there were no failures + +DESCRIPTION: + + PRETTY-PRINT-CHECK-DIRECTORY checks DIR for any errors, dumping them to output + and returning a single flag. + + Unlike check-directory, PRETTY-PRINT-CHECK-DIRECTORY is built for continuous + integration, dumping errors to standard out and returning a singular result. + +EXAMPLES: + + (pretty-print-check-directory \"src\") => nil" (let ((checks (check-directory dir))) (format t "In ~A: Checked ~A files with ~A failures~%~%" diff --git a/wiki b/wiki new file mode 160000 index 0000000..3e6a2ca --- /dev/null +++ b/wiki @@ -0,0 +1 @@ +Subproject commit 3e6a2caa124f2537f8ff9ad2c53f4bbaa285cb63