Add basic quick README
Getty Ritter
5 years ago
| 1 | The `collage` tool is a tool for writing documents that rely on code samples while keeping the code samples up-to-date. | |
| 2 | ||
| 3 | # Including an Entire Source File | |
| 4 | ||
| 5 | To create a `collage` project, create a directory that contains a file called `collage` as well as one or more subdirectories that contain the code that you want to expose, and a document in whatever plain text format you want. For example, say that we have a piece of Python source we'd like to write about: let's create a project directory as well as the subdirectory for the Python program, and initialize it with a trivial Python program: | |
| 6 | ||
| 7 | ```bash | |
| 8 | $ mkdir my-post | |
| 9 | $ mkdir my-post/python-example | |
| 10 | $ echo "print 'Hello, world!'" >my-post/python-example/main.py | |
| 11 | ``` | |
| 12 | ||
| 13 | Now, let's write a document: save the following to `my-document.md`: | |
| 14 | ||
| 15 | ```markdown | |
| 16 | Here is a document describing a snippet of Python source. A 'Hello | |
| 17 | World' program in Python looks like this: | |
| 18 | ||
| 19 | ~~~python | |
| 20 | «hello» | |
| 21 | ~~~ | |
| 22 | ||
| 23 | Isn't that easy? | |
| 24 | ``` | |
| 25 | ||
| 26 | Notice that the code block there contains a string in guillemets (`«hello»`) instead of the actual source code. Now, finally, we write a `collage` file that ties these together: | |
| 27 | ||
| 28 | ||
| 29 | ``` | |
| 30 | (document | |
| 31 | # first, we tell it which document we care about | |
| 32 | "my-document.md" | |
| 33 | ||
| 34 | # then, we define a "source": this is a project we're drawing | |
| 35 | # from to get source code. We called it «hello» up above, so | |
| 36 | # we're going to give it the name "hello", and we've put it | |
| 37 | # in the directory "python-example". Our test build will be | |
| 38 | # simply running it, and finally, we'll point to the file | |
| 39 | # "main.py" as the file whose source code we care about | |
| 40 | { | |
| 41 | name "hello" | |
| 42 | dir "python-example" | |
| 43 | cmd [ "python main.py" ] | |
| 44 | expose (file "main.py") | |
| 45 | } | |
| 46 | ) | |
| 47 | ``` | |
| 48 | ||
| 49 | In our directory, we can now run `collage test` and we'll get output that looks like the following: | |
| 50 | ||
| 51 | ```bash | |
| 52 | $ collage test | |
| 53 | testing my-document.md | |
| 54 | - building source hello | |
| 55 | - running "python main.py" in my-post/python-example | |
| 56 | Hello, world | |
| 57 | ``` | |
| 58 | ||
| 59 | we can also run `collage splice` to stitch the source code in question into our document: | |
| 60 | ||
| 61 | ```bash | |
| 62 | $ collage splice | |
| 63 | Here is a document describing a snippet of Python source. A 'Hello | |
| 64 | World' program in Python looks like this: | |
| 65 | ||
| 66 | ~~~python | |
| 67 | print 'Hello, world' | |
| 68 | ~~~ | |
| 69 | ||
| 70 | Isn't that easy? | |
| 71 | ``` | |
| 72 | ||
| 73 | # Including Multiple Source Files Per Project | |
| 74 | ||
| 75 | In addition to exposing a single source file, we can expose more than one. Replace the `(file "my-file")` expression with a map from names to files, and then use forward slashes to refer to names within this mapping. For example, if I added a `helper.py` file, and I wanted to use both, my Markdown file could reference `«hello/main»` and `«hello/helper»`, and my `collage` file could be updated to include | |
| 76 | ||
| 77 | ``` | |
| 78 | # ... | |
| 79 | expose { | |
| 80 | main (file "main.py") | |
| 81 | helper (file "helper.py") | |
| 82 | } | |
| 83 | # ... | |
| 84 | ``` | |
| 85 | ||
| 86 | # Including Only Some Part of a Source File | |
| 87 | ||
| 88 | If we have only some parts of a source file we want to draw attention to, we can `expose` using the the `sections` expression instead. Let's say we expand `main.py` above to look like this: | |
| 89 | ||
| 90 | ```python | |
| 91 | import sys | |
| 92 | ||
| 93 | # «main» | |
| 94 | def main(): | |
| 95 | sys.stdout.write("Hello, world!\n") | |
| 96 | # «end» | |
| 97 | ||
| 98 | if __name__ == '__main__': | |
| 99 | main() | |
| 100 | ``` | |
| 101 | ||
| 102 | The two comment lines around the `main` function demarcate a _section_ of the file: `collage` will look for those substrings and then select only the lines of the file in between those two. We can refer to that section identifier just like we refer to multiple files above, as `«helper/main»`. We can then update our `collage` file to read: | |
| 103 | ||
| 104 | ``` | |
| 105 | # ... | |
| 106 | { | |
| 107 | name "hello" | |
| 108 | dir "python-example" | |
| 109 | cmd [ "python main.py" ] | |
| 110 | expose (sections "main.py") | |
| 111 | } | |
| 112 | # ... | |
| 113 | ``` |