basis/tools/scaffold/scaffold-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: arrays help.markup help.syntax kernel strings words vocabs sequences ;
   4 IN: tools.scaffold
   5
   6 HELP: developer-name
   7 { $description "Set this symbol to hold your name so that the scaffold tools can generate the correct file header for copyright. Setting this variable in your .factor-boot-rc file is recommended." }
   8 { $code "USING: namespaces tools.scaffold ;\n\"Stacky\" developer-name set-global" } ;
   9
  10 HELP: help.
  11 { $values
  12     { "word" word } }
  13 { $description "Prints out scaffold help markup for a given word." } ;
  14
  15 HELP: scaffold-docs
  16 { $values { "obj" object } }
  17 { $description "Takes a word or vocabulary name and creates a help file with scaffolded help for each word. For vocabulary names, if a file exists this word will not do anything." } ;
  18
  19 HELP: scaffold-undocumented
  20 { $values
  21     { "string" string } }
  22 { $description "Prints scaffolding documentation for undocumented words in a vocabulary except for automatically generated class predicates." } ;
  23
  24 { scaffold-docs scaffold-undocumented scaffold-examples } related-words
  25
  26 HELP: scaffold-examples
  27 { $values
  28     { "word" word }
  29 }
  30 { $description "Create some examples for a word with a using list that includes vocabularies the word is in and the " { $vocab-link "prettyprint" } " vocabulary. You are then expected to change the header " { $snippet "Example:" } " to something more descriptive." }
  31 { $examples
  32     "Create docs for the + word:"
  33     { $example "USING: math tools.scaffold prettyprint ;"
  34         "\\ + scaffold-examples"
  35         "{ $examples
  36     \"Example:\"
  37     { $example \"USING: math prettyprint ;\"
  38         \"\"
  39         \"\"
  40     }
  41     \"Example:\"
  42     { $example \"USING: math prettyprint ;\"
  43         \"\"
  44         \"\"
  45     }
  46 }"
  47     }
  48 } ;
  49
  50 HELP: scaffold-core
  51 { $values
  52     { "string" string }
  53 }
  54 { $description "Create a placeholder vocabulary in the core vocabulary root." } ;
  55
  56 HELP: scaffold-basis
  57 { $values
  58     { "string" string }
  59 }
  60 { $description "Create a placeholder vocabulary in the basis vocabulary root." } ;
  61
  62 HELP: scaffold-extra
  63 { $values
  64     { "string" string }
  65 }
  66 { $description "Create a placeholder vocabulary in the extra vocabulary root." } ;
  67
  68 HELP: scaffold-work
  69 { $values
  70     { "string" string }
  71 }
  72 { $description "Create a placeholder vocabulary in the work vocabulary root." } ;
  73
  74 HELP: scaffold-authors
  75 { $values
  76     { "vocab" "a vocabulary specifier" }
  77 }
  78 { $description "Creates an authors.txt file using the value in " { $link developer-name } ". This word only works if no authors.txt file yet exists." } ;
  79
  80 HELP: scaffold-summary
  81 { $values
  82     { "vocab" "a vocabulary specifier" } { "summary" string }
  83 }
  84 { $description "Creates a summary.txt file with the given summary. This word only works if no summary.txt file yet exists." } ;
  85
  86 HELP: scaffold-tags
  87 { $values
  88     { "vocab" "a vocabulary specifier" } { "tags" string }
  89 }
  90 { $description "Creates a tags.txt file with the given tags. This word only works if no tags.txt file yet exists." } ;
  91
  92 HELP: scaffold-tests
  93 { $values
  94     { "vocab" "a vocabulary specifier" }
  95 }
  96 { $description "Takes an existing vocabulary and creates an empty tests file. This word only works if no tests file yet exists." } ;
  97
  98 HELP: scaffold-vocab-in
  99 { $values
 100     { "vocab-root" "a vocabulary root string" } { "string" string } }
 101 { $description "Creates a directory in the given root for a new vocabulary and adds a main .factor file and an authors.txt file." } ;
 102
 103 HELP: scaffold-vocab
 104 { $values { "string" string } }
 105 { $description "Searches parent vocabularies for an appropriate root to create a new vocabulary and adds a main .factor file and an authors.txt file." } ;
 106
 107 HELP: scaffold-emacs
 108 { $description "Touches the .emacs file in your home directory and provides a clickable link to open it in an editor." } ;
 109
 110 HELP: scaffold-factor-boot-rc
 111 { $description "Touches the .factor-boot-rc file in your home directory and provides a clickable link to open it in an editor." } ;
 112
 113 HELP: scaffold-factor-rc
 114 { $description "Touches the .factor-rc file in your home directory and provides a clickable link to open it in an editor." } ;
 115
 116 HELP: scaffold-factor-roots
 117 { $description "Touches the .factor-roots file in your home directory and provides a clickable link to open it in an editor." } ;
 118
 119 HELP: scaffold-rc
 120 { $values
 121     { "path" "a pathname string" }
 122 }
 123 { $description "Touches the given path in your home directory and provides a clickable link to open it in an editor." } ;
 124
 125 HELP: using
 126 { $description "Stores the vocabularies that are pulled into the documentation file from looking up the stack effect types." } ;
 127
 128 HELP: make-unit-test
 129 { $values
 130     { "answer" string } { "code" string }
 131     { "str" string }
 132 }
 133 { $description "Takes a code snippet and an answer string and returns a unit-test code snippet for use with " { $vocab-link "tools.test" } " vocabulary. The answer string should represent an array of values left on the stack by the code snippet." }
 134 { $examples
 135     { $example
 136         "USING: io tools.scaffold ;"
 137         "\"{ 2 2 3 }\" \"3 2 dup rot\" make-unit-test write"
 138         "{ 2 2 3 } [\n    3 2 dup rot\n] unit-test"
 139     }
 140 }
 141 { $see-also read-unit-test } ;
 142
 143 HELP: run-string
 144 { $values
 145     { "string" string }
 146     { "datastack" array }
 147 }
 148 { $description "Parses and executes the string on an empty datastack, returning the resulting datastack as an array." }
 149 { $see-also read-unit-test } ;
 150
 151 HELP: read-unit-test
 152 { $values
 153     { "str/f" { $maybe string } }
 154 }
 155 { $description "Consumes a code snippet from input stream, runs it, and returns a unit-test code snippet for use with " { $vocab-link "tools.test" } " vocabulary. If no characters were read before the empty line returns " { $link f } " instead. On the interactive listener input is consumed until an empty line." }
 156 { $see-also run-string make-unit-test scaffold-unit-tests } ;
 157
 158 HELP: read-unit-tests
 159 { $values
 160     { "str" string }
 161 }
 162 { $description "Reads code snippets by the means of " { $link read-unit-test } " until two empty lines are input. Returns them separated with two newlines." } ;
 163
 164 HELP: scaffold-unit-tests
 165 { $values
 166     { "vocab" "a vocabulary specifier" }
 167 }
 168 { $description "Takes an existing vocabulary and creates an empty test file if one isn't present yet. Reads code snippets separated by empty lines from input stream until a double empty line. After each snippet prints a unit test based on the snippet to output stream and appends it to the test file." { $nl }
 169 "This word enables quick creation of unit tests by recording outputs of code snippets and getting immediate feedback to fix any discrepancies as they occur." }
 170 { $see-also read-unit-test } ;
 171
 172 ARTICLE: "tools.scaffold" "Scaffold tool"
 173 "Scaffold setup:"
 174 { $subsections developer-name }
 175 "Generate new vocabs:"
 176 { $subsections scaffold-vocab scaffold-core scaffold-basis scaffold-extra scaffold-work }
 177 "Generate help scaffolding:"
 178 { $subsections
 179     scaffold-docs
 180     scaffold-undocumented
 181     scaffold-examples
 182     scaffold-n-examples
 183     help.
 184 }
 185 "Types that are unrecognized by the scaffold generator will be of type " { $link object } ". The developer should change these to strings that describe the stack effect names instead." $nl
 186 "Scaffolding a configuration file:"
 187 { $subsections
 188     scaffold-rc
 189     scaffold-factor-boot-rc
 190     scaffold-factor-rc
 191     scaffold-factor-roots
 192     scaffold-emacs
 193 }
 194 "Scaffolding a test file:"
 195 { $subsections
 196     scaffold-tests
 197     scaffold-unit-tests
 198     read-unit-test
 199 }
 200 ;
 201
 202 ABOUT: "tools.scaffold"