Add coverage, get to near 100
[sheep] / README.md
1 # Common Lisp Document Generator
2
3 Enforcement of documentation guidelines for my Common Lisp Projects, as well as conversion to markdown for my github repositories.
4
5 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.
6
7 If you like, you can [download it](https://consxy.com/sheep/releases/0.3/docgen_0.3.tar.gz)
8
9 ## Usage
10
11 See [Reference](https://consxy.com/sheep/reference.html) for usage information (generated by this package).
12
13 To see how that page was created, take a look at bin/generatedocs.sh
14
15 ## Package documentation
16
17 Packages are documented by sections broken up by one empty line, with the first section limited to 120 characters.
18
19 ## Structure/Condition documentation
20
21 Requirements are the same as the package documentation.
22
23 ## Variable documentation
24
25 Variables should follow the template:
26
27 ```
28 *VARIABLE*
29
30 VALUE TYPE:
31
32   a generalized boolean
33
34 INITIAL VALUE:
35
36   NIL
37
38 DESCRIPTION:
39
40   *VARIABLE* is expected to be a boolean, but
41   most anything can be it.
42
43 EXAMPLES:
44
45   (let ((*variable* t)) (go)) => let-it-go
46 ```
47
48 There are three required sections and one optional section.  ```VALUE TYPE```, ```INITIAL VALUE```, and ```DESCRIPTION``` are freeform, with the ```EXAMPLES``` section following the same rules as below in the function documentation.
49
50 ### 
51
52 ## Function documentation
53
54 Functions should follow the template:
55
56 ```
57 FUNC PATH => RESULT
58
59   RESULT: SUCCESS-RESULTS | FAILURE-RESULT
60   SUCCESS-RESULTS: SUCCESS-RESULT*
61   SUCCESS-RESULT: (:success FILENAME)
62   FAILURE-RESULT: (:failure FILENAME MSG)
63
64 ARGUMENTS AND VALUES:
65
66   PATH: a pathname
67   FILENAME: the file this func was run on
68   MSG: a string containing the failure message
69
70 DESCRIPTION:
71
72   FUNC runs all the things against a file located at PATH and returns
73   as soon as the first func error is found.
74
75 EXAMPLES:
76
77   (func #P\"path/to/file.lisp\" t) => (:success \"path/to/file.lisp\")
78   (func #P\"path/to/error.lisp\" nil) => (:failure \"path/to/error.lisp\" \"Error msg\")
79 ```
80
81 There are four sections to each function definition:
82
83 ### Header section
84
85 Arguments should all be upper case, but &rest, &optional, and &key should be lower case.  Arguments are seperated by a space.
86
87 Results should also be upper case, and in the case of values, separated by commas.
88
89 Types can be further elucidated by providing more information either as a list of options seperated by pipes, a tuple contained in parens, or a list denoted by an *
90
91 ### Arguments and values section:
92
93 All the types that weren't broken down into subtypes must be explained.  The form is type name in all upper case, a colon, then a description.  That description can have upper case type names in it which will then get italicized later.
94
95 ### Description
96
97 Descriptins should be indented two spaces, and not longer than 120 characters wide.  Like the arguments and values, upper cased types will be italicized later.
98
99 ### Examples
100
101 This section is optional.
102
103 Examples are of the form:  example-code => example result