Add documentation and docgen

diff --git a/.gitmodules b/.gitmodules
new file mode 100644 (file)
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 e7fc066b5e2180bf630957d3b34f57cd83baaba9..368439fbb287d06778b5642c4eba782cbf8ed073 100644 (file)
--- a/.travis.yml
+++ b/.travis.yml
@@ -1,5 +1,5 @@
 before_install:
 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:
   - chmod +x travissbcl
 
 script:

diff --git a/README.md b/README.md
index 290c324eb9a130c6d4a7900979ebdf9eb23df2d0..209be708e7daaab6a3f59f7c6b7f51dec545a7f1 100644 (file)
--- a/README.md
+++ b/README.md
@@ -27,10 +27,6 @@ If you like, you can [download it](https://github.com/frankduncan/style-checker/
 
 ## Usage
 
 
 ## 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 20480dabc1b5a0bdab135cb28318f233a971d34d..622943250fcbe162aa4284fb673983fee9ad0a30 100755 (executable)
--- 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 &&
 
 ( 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 "(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)' \
 
   --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 (executable)
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 489212025ef3010eee1f89fcde8245226ed1be0b..17e87e15ec1224e7df07875a99ab7b7a1b514748 100644 (file)
--- 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))
 (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)
 
 (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 (file)
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 31eb3e33214a4fd5f94e026cc8a6eacf5ba0412c..504f2ac29cc216cc0e7170b95eadab1106f84cee 100644 (file)
--- a/src/main/package.lisp
+++ b/src/main/package.lisp
@@ -1,2 +1,9 @@
 (defpackage #:syntax-checker (:use :cl)
 (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 79cf0f53ca41a6bcb9e37fb2f57a0105bc1ab962..f6c31da66c7415ee683e1088287c6a5b64e08070 100644 (file)
--- 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)
 
   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
 
   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)
    (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)
  (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)
   (+ (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~%~%"
  (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 (submodule)
index 0000000..3e6a2ca
--- /dev/null
+++ b/wiki
@@ -0,0 +1 @@
+Subproject commit 3e6a2caa124f2537f8ff9ad2c53f4bbaa285cb63