Merge pull request #196 from CFiggers/master

Overhaul spork's docs

README.md

@@ -20,3 +20,17 @@ as seen in the example for the part.
 
 Spork contains third-party dependencies in the `deps/` directory. All dependencies are MIT/X11 licensed, or public domain.
 Licenses for individual components can be found along with the source code in the `deps/` directory.
+
+## Documentation
+
+Spork's documentation is written using [Mendoza](https://github.com/bakpakin/mendoza).
+ The docs are most easily read by first building and then serving the .mdz files in `doc/` using Mendoza.
+ You can then access the served static site using a browser.
+
+- First, make sure you have [Janet](https://janet-lang.org/) and [jpm](https://janet-lang.org/docs/jpm.html) installed. See [the Janet docs](https://janet-lang.org/introduction.html) for more information on this.
+- Next, install Mendoza (to install globally, run `[sudo] jpm install mendoza`). For more information on Mendoza, see [the Mendoza project on GitHub](https://github.com/bakpakin/mendoza).
+- Clone this repo locally (e.g. using `git clone https://github.com/janet-lang/spork.git`).
+- From the spork project root (`cd spork` if you just cloned it) run `mdz build && mdz serve`.
+
+While the Mendoza server process is running, you can navigate to http://localhost:8000 to view the spork docs as a static site.
+

doc/argparse.mdz → doc/api/argparse.mdz

@@ -1,8 +1,7 @@
 {:title "argparse"
  :author "Calvin Rose"
  :license "MIT"
- :template "mdzdoc/main.html"
- :order 0}
+ :template "mdzdoc/main.html"}
 ---
 
 A moderately opinionated argument parser for
@@ -59,3 +58,7 @@ into an array, include @code`:default {:kind :accumulate}` in your
 arguments to @code`argparse`.
 
 Run @code`(doc argparse/argparse)` after importing for more information.
+
+## Reference
+
+@api-docs("../../spork" "argparse")

doc/base64.mdz → doc/api/base64.mdz

@@ -1,15 +1,14 @@
-{:title "Base64"
+{:title "base64"
  :author "Josef Pospíšil"
  :license "MIT"
- :template "mdzdoc/main.html"
- :order 99}
+ :template "mdzdoc/main.html"}
 ---
 
-# Base64
-
 This module contains Base64 utilities.
 
-## base64/encode
+## Examples
+
+### base64/encode
 
 Converts a string of any format (UTF-8, binary, ..) to base64 encoding.
 
@@ -18,8 +17,7 @@ Converts a string of any format (UTF-8, binary, ..) to base64 encoding.
 # => "dGhpcyBpcyBhIHRlc3Q="
 ```
 
-
-## base64/decode
+### base64/decode
 
 Converts a base64 encoded string to its binary representation of any format 
 (UTF-8, binary, ...).
@@ -29,3 +27,6 @@ Converts a base64 encoded string to its binary representation of any format
 # => "this is a test"
 ```
 
+## Reference
+
+@api-docs("../../spork" "base64")

doc/api/build-rules.mdz

@@ -0,0 +1,11 @@
+{:title "build-rules"
+ :template "mdzdoc/main.html"}
+---
+
+Run commands that produce files in an incremental manner.
+Use to implement a build system.
+
+## Reference
+
+@api-docs("../../spork" "build-rules")
+

doc/api/cc.mdz

@@ -0,0 +1,28 @@
+{:title "cc"
+ :template "mdzdoc/main.html"}
+ ---
+
+Improved version of the C Compiler abstraction from JPM that should be more correct, composable, and
+have less configuration.
+
+Wrapper around the system C compiler for compiling Janet native modules and executables.
+Opinionated and optimized for use with Janet, and does not actually run
+commands unless specified with (dyn *visit*). Also included is package config integration.
+Headers, static libraries, and dynamic libraries can all be used from `(dyn *syspath*)`.
+
+## Example usage
+
+@codeblock[janet]```
+(use spork/cc)
+
+(search-static-libraries "m" "rt" "dl")
+(search-dynamic-libraries "janet")
+(pkg-config "sdl2" "vulkan")
+(with-dyns [*defines* {"GAME_BUILD" "devel-0.0"}
+ *visit* visit-execute-if-stale]
+ (compile-and-link-executable "game" "main.c" "sound.c" "graphics.c"))
+```
+
+## Reference
+
+@api-docs("../../spork" "cc")

doc/api/channel.mdz

@@ -0,0 +1,9 @@
+{:title "channel"
+ :template "mdzdoc/main.html"}
+ ---
+
+Channel utilities for Janet.
+
+## Reference
+
+@api-docs("../../spork" "channel")

doc/api/cjanet.mdz

@@ -0,0 +1,14 @@
+{:title "cjanet"
+ :template "mdzdoc/main.html"}
+ ---
+
+A DSL that compiles to C. 
+ Improved version of jpm/cgen that is more amenable to Janet integration, macros, and meta-programming.
+
+The semantics of the language are basically the
+same as C so a higher level language (or type system) should be built on top of this. 
+ This IR emits a very useful subset of valid C 99.
+
+## Reference
+
+@api-docs("../../spork" "cjanet")

doc/api/cmath.mdz

@@ -0,0 +1,7 @@
+{:title "cmath"
+ :template "mdzdoc/main.html"}
+ ---
+
+## Reference
+
+@api-docs("../../spork" "cmath")

doc/api/crc.mdz

@@ -0,0 +1,11 @@
+{:title "crc"
+ :template "mdzdoc/main.html"}
+ ---
+
+Generate CRC (Cyclic Redundancy Check) variants. 
+ Rather than compile separate variants, we have code to generate the needed tables. 
+ Keeps build simple, footprint small but with many variants accessible.
+
+## Reference
+
+@api-docs("../../spork" "crc")

doc/api/cron.mdz

@@ -0,0 +1,38 @@
+{:title "cron"
+ :template "mdzdoc/main.html"}
+ ---
+
+Timer library for interfacing with the UNIX crontab format. 
+
+The cron format support is based on the unix cron syntax, with an optional seconds field. 
+ Each field can be a comma separated list of individual values or a range of values. 
+
+A range has three variants as follows: 
+@ol{
+ @li{Two values with a "-" between them, optionally followed by a "/" and a step value.}
+ @li{An asterisk ("*") followed by a "/" and a step value. This implies every "step" value.}
+ @li{A single value followed by a "/" and a step value. This implies every "step" value starting with the single value. I.e., 2/3 implies every 3 units from 2 to max units.}}
+
+A single asterisk ("*") can be used to denote all possible values.
+
+The fields:
+@ul{
+ @li{minutes: 0-5 } 
+ @li{hours: 0-2 } 
+ @li{day of month: 1-3 } 
+ @li{month: 1-12. Also allowed are the following month codes in any case } 
+ jan,feb,mar,apr,may,jun,jul,aug,sep,oct,nov,dec
+ @li{day of week: 0-7, where 0 or 7 is sunday, monday is 1, etc. allows the following day codes (any case)} 
+ sun,mon,tue,wed,thu,fri,sat
+ @li{ seconds (optional): 0-5}}
+
+Cron schedules are represented as tuples of 7 values, a string representation, followed
+by 6 bitmaps representing matching timestamps. Bitmaps are represented as any byte sequence.
+
+@codeblock`[string-rep minutes hours day-of-month month day-of-week seconds]`
+
+Note that we have second precision here as opposed to minute precision.
+
+## Reference
+
+@api-docs("../../spork" "cron")

doc/data.mdz → doc/api/data.mdz

@@ -1,8 +1,7 @@
 {:title "data"
  :author "Caleb Figgers"
  :license "MIT"
- :template "mdzdoc/main.html"
- :order 1}
+ :template "mdzdoc/main.html"}
 ---
 
 @p{@link[https://clojure.org/]{Clojure} contains a very useful core library (or "namespace" in Clojure parlance) called @link[https://clojure.github.io/clojure/clojure.data-api.html]{clojure.data} (@link[https://github.com/clojure/clojure/blob/51c6d7a70912a8f65e81a8e11ae6f56c94920725/src/clj/clojure/data.clj]{source}). It contains one "exported" function: @code`clojure.data/diff`. This addition to spork, @code`data.janet`, should exactly replicate the behavior of @code`clojure.data/diff` using Janet tables, structs, arrays, and tuples in place of their Clojure equivalents.}
@@ -11,7 +10,7 @@
 
 The @code`diff` function recursively compares the structure and contents of two data structures (struct, table, tuple, array) and returns an array with three elements:
 
-@codeblock`@[things-only-in-a things-only-in-b things-in-both]`
+@codeblock[janet]`@[things-only-in-a things-only-in-b things-in-both]`
 
 In the case of nested associative data structures (i.e., tables and structs), the comparison is recursive and the data structures are neatly partitioned into the same @code`@[things-only-in-a things-only-in-b things-in-both]` structure, but arbitrary levels deep in the two original associative data structures.
 
@@ -36,3 +35,7 @@ The return is @code`@[@{:a 1 :c @{:e 4}} @{:a 4 :c @{:e 5 :f 6}} @{:b 2 :c @{:d
  @li{the nested value of @code`:e` appears in both and is different in each one (so @code`:c` is a key in both the first and second returned table, containing the value @code`:e` with with each value set as seen in the first and second original structs), and}
  @li{the key/value pair @code`:f` 6 only appears in the latter original struct (so only the second returned table contains @code`:f` and its value).}
 }
+
+## Reference
+
+@api-docs("../../spork" "data")

doc/api/ev-utils.mdz

@@ -0,0 +1,9 @@
+{:title "ev-utils"
+ :template "mdzdoc/main.html"}
+ ---
+
+Module for parallel execution utilities with Janet.
+
+## Reference
+
+@api-docs("../../spork" "ev-utils")

doc/formatting.mdz → doc/api/fmt.mdz

@@ -1,24 +1,29 @@
-{:title "Formatting"
+{:title "fmt"
  :author "Calvin Rose"
  :license "MIT"
- :template "mdzdoc/main.html"
- :order 2}
+ :template "mdzdoc/main.html"}
 ---
 
 Provides a way to format Janet code strings and files.
 
-## Strings
+## Examples
+
+### Strings
 
 @codeblock[janet]```
 (import spork/fmt)
 
 (fmt/format "(def a\n 3 )") => @"(def a\n 3)\n"
 ```
 
-## Files
+### Files
 
 @codeblock[janet]```
 (import spork/fmt)
 
 (fmt/format-file "main.janet")
 ```
+
+## Reference
+
+@api-docs("../../spork" "fmt")

doc/api/generators.mdz

@@ -0,0 +1,20 @@
+{:title "generators"
+ :author "Z. D. Smith"
+ :license "BSD3"
+ :template "mdzdoc/main.html"}
+---
+
+A @strong[generator] is an iterable data structure which yields individual values whenever called, potentially until its internal values are exhausted, at which point it's considered @i[dead].
+
+This operation makes them very useful for:
+
+@ul{@li{Asynchronous behaviour}
+ @li{Memory-sensitive applications, where it's not necessary to keep an entire sequence in memory at once}
+ @li{Infinite sequences}}
+
+NB: Certain functions (specifically @code`run` and @code`to-array`) will create an infinite loop if their argument is an infinite generator!
+
+## Reference
+
+@api-docs("../../spork" "generators")
+

doc/api/getline.mdz

@@ -0,0 +1,9 @@
+{:title "getline"
+ :template "mdzdoc/main.html"}
+ ---
+
+Module for fiber-based sequence combinators rather than array-based combinators, as are in the core library.
+
+## Reference
+
+@api-docs("../../spork" "getline")

doc/htmlgen.mdz → doc/api/htmlgen.mdz

@@ -1,23 +1,16 @@
-{:title "HTMLgen"
+{:title "htmlgen"
  :author "Calvin Rose"
  :license "MIT"
- :template "mdzdoc/main.html"
- :order 4}
+ :template "mdzdoc/main.html"}
 ---
 
 HTMLgen is a rendering engine that can render plain data structures into
 an HTML string. Its API has only one constant and two functions:
 
 @ul{
- @li{constant `doctype` is a string with html5 doctype header}
- @li{function `raw` returns the function that will add the raw string,
- passed as an argument to the function, to the output, when rendered,
- without any escaping.}
- @li{function `html` has one required argument `data` with the data structure
- rendered into bytes with HTML code. And optional `buf` to which function
- renders final bytes. If you do not provide the `buf`, it will create
- a new one.}
-}
+ @li{constant @code`doctype` is a string with html5 doctype header}
+ @li{function @code`raw` returns the function that will add the raw string, passed as an argument to the function, to the output, when rendered, without any escaping.}
+ @li{function @code`html` has one required argument @code`data` with the data structure rendered into bytes with HTML code. And optional @code`buf` to which function renders final bytes. If you do not provide the @code`buf`, it will create a new one.} }
 
 ## Rules for rendering data structures
 
@@ -42,20 +35,21 @@ We will show how HTMLgen renders from the data structure by dissecting
 the example above:
 
 @ul{
- @li{`array` (and `fiber` which is not in the example) each member of
+ @li{`array` (and @code`fiber` which is not in the example) each member of
  the sequence renders by one of these rules.}
- @li{`tuple` represents the HTML tag. The first member must be the name of
+ @li{@code`tuple` represents the HTML tag. The first member must be the name of
  the HTML tag. The second member can be a dictionary with HTML attributes
  for the HTML tag. All the other members are children of the tag and renders
  according to these rules.}
- @li{`string`, `buffer`, `number` and `boolean` coerces to string and,
+ @li{@code`string`, @code`buffer`, @code`number` and @code`boolean` coerces to string and,
  if necessary, escaped and pushed to the buffer.}
- @li{`function` gets the buffer, with which it can do whatever it wants to,
+ @li{@code`function` gets the buffer, with which it can do whatever it wants to,
  presumably push some more content, but anything.}
- @li{`nil` do not do anything to the buffer.}
+ @li{@code`nil` do not do anything to the buffer.}
 }
 
-As you may see, the rules are straightforward, yet with the `fiber`
-and `function` types you have pretty endless possibilities when constructing
-the HTML code from data structures
+As you may see, the rules are straightforward, yet with the @code`fiber` and @code`function` types you have pretty endless possibilities when constructing the HTML code from data structures.
+
+## Reference
 
+@api-docs("../../spork" "htmlgen")

doc/http.mdz → doc/api/http.mdz

@@ -1,15 +1,16 @@
-{:title "HTTP"
+{:title "http"
  :author "Calvin Rose"
  :license "MIT"
- :template "mdzdoc/main.html"
- :order 5}
+ :template "mdzdoc/main.html"}
 ---
 
 The @code`http` module is an HTTP/1.1 parser, server and client module. It proves a simple server implementation, client, support for chunked encoding.
 The @code`http` module is also non-blocking, so a single thread can run
 many clients, servers, and connections at once.
 
-## Server
+## Examples
+
+### Server
 
 @codeblock[janet]```
 (import spork/http)
@@ -25,7 +26,7 @@ many clients, servers, and connections at once.
 (http/server handler "127.0.0.1" "9000")
 ```
 
-## Client
+### Client
 
 @codeblock[janet]```
 (import spork/http)
@@ -34,3 +35,7 @@ many clients, servers, and connections at once.
 (def body (http/read-body response))
 (print body)
 ```
+
+## Reference
+
+@api-docs("../../spork" "http")