3 (define-condition validation-failure nil ((msg :initarg :msg :reader validation-failure-msg))
4 (:documentation "Used internally for docgen parts to signal a validation error."))
6 (defun get-symb-type (symb)
8 ;((documentation symb 'variable) :variable)
9 ((documentation symb 'structure) :structure)
10 ((documentation symb 'function) :function)))
12 (defun validate-package (pkg)
13 "VALIDATE-PACKAGE PKG => FAILURES
16 FAILURE: (:failure SYMB MSG)
21 SYMB: Symbol the check failed on
22 MSG: Message containing information about the failure
26 VALIDATE-PACKAGE takes in PKG and validates that all the external symbols
27 adhere to documentation guidelines, exist, and can be parsed to be used
30 Only one error per symbol will be reported at a time, all concatenated to
31 a list in the aforementioned form."
33 ((with-success-check (symb &rest f)
36 (validation-failure (v) (list :failure ,symb (validation-failure-msg v))))))
39 (do-external-symbols (symb pkg) (push symb symbs))
40 (setf symbs (sort symbs #'string< :key #'symbol-name))
43 (list (with-success-check pkg (docgen-pkg:doc->ast (find-package pkg))))
46 (with-success-check symb
47 (case (get-symb-type symb)
48 (:function (docgen-func:doc->ast symb))
49 (:structure (docgen-struc:doc->ast symb))
50 (t (error (make-condition 'validation-failure :msg (format nil "Symbol ~A has no documentation" symb)))))))
53 (defun pretty-print-validate-packages (&rest pkgs)
54 "PRETTY-PRINT-VALIDATE-PACKAGES &rest PKGS => SUCCESS
60 SUCCESS: Whether or not all symbols passed validation
65 PRETTY-PRINT-VALIDATE-PACKAGES takes PKGS and runs validation on all of them.
66 It dumps to standard out failures as it comes upon them, finally returning
67 whether it was successful or not.
69 This can be used in travis tests to ensure that documentation can be generated
74 (pretty-print-validate-packages :pkg1 :pkg2) => t"
80 ((failures (validate-package pkg)))
83 (format t "In ~A : ~A, documentation error found:~% ~A~%" pkg (second failure) (third failure)))
88 (defun table-of-contents (pkg)
89 (format nil "## Contents~%~%~{~{* **~A [~A](#~A)** - ~A~}~%~}"
92 (do-external-symbols (symb pkg) (push symb symbs))
93 (setf symbs (sort symbs #'string< :key #'symbol-name))
96 (case (get-symb-type symb)
99 (docgen-func:ast->category-name (docgen-func:doc->ast symb))
100 (docgen-func:ast->short-name (docgen-func:doc->ast symb))
101 (docgen-func:ast->link (docgen-func:doc->ast symb))
102 (docgen-func:ast->short-desc (docgen-func:doc->ast symb))))
105 (docgen-struc:ast->category-name (docgen-struc:doc->ast symb))
106 (docgen-struc:ast->short-name (docgen-struc:doc->ast symb))
107 (docgen-struc:ast->link (docgen-struc:doc->ast symb))
108 (docgen-struc:ast->short-desc (docgen-struc:doc->ast symb))))))
111 (defun export-package (pkg)
112 "EXPORT-PACKAGE PKG => MARKDOWN
114 ARGUMENTS AND VALUES:
116 PKG: A package symbol
117 MARKDOWN: A string containing the markdown representation of this packages documentation
121 EXPORT-PACKAGE takes in PKG and converts all the documentation for the symbols
122 into markdown with the hope of emulating the hyperspec style.
124 It should only be run after the package has been validated, as it assumes that
125 all documentation it gets will be valid."
128 (do-external-symbols (symb pkg) (push symb symbs))
129 (setf symbs (sort symbs #'string< :key #'symbol-name))
130 (with-output-to-string (str)
131 (format str "~A~%~%" (docgen-pkg:ast->md (docgen-pkg:doc->ast (find-package pkg))))
132 (format str "~A~%" (table-of-contents pkg))
133 (format str "~{~A~^~%~}"
136 (case (get-symb-type symb)
137 (:function (docgen-func:ast->md (docgen-func:doc->ast symb)))
138 (:structure (docgen-struc:ast->md (docgen-struc:doc->ast symb)))))