| 1 | |
The `collage` tool is a tool for writing documents that rely on code samples while keeping the code samples up-to-date.
|
| 1 |
The `bricoleur` tool is a tool for writing documents that rely on code samples while keeping the code samples up-to-date.
|
| 2 | 2 |
|
| 3 | 3 |
# Including an Entire Source File
|
| 4 | 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:
|
| 5 |
To create a `bricoleur` project, create a directory that contains a file called `bricoleur` 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 | 6 |
|
| 7 | 7 |
```bash
|
| 8 | 8 |
$ mkdir my-post
|
|
| 23 | 23 |
Isn't that easy?
|
| 24 | 24 |
```
|
| 25 | 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:
|
| 26 |
Notice that the code block there contains a string in guillemets (`«hello»`) instead of the actual source code. Now, finally, we write a `bricoleur` file that ties these together:
|
| 27 | 27 |
|
| 28 | 28 |
|
| 29 | 29 |
```
|
|
| 46 | 46 |
)
|
| 47 | 47 |
```
|
| 48 | 48 |
|
| 49 | |
In our directory, we can now run `collage test` and we'll get output that looks like the following:
|
| 49 |
In our directory, we can now run `bricoleur test` and we'll get output that looks like the following:
|
| 50 | 50 |
|
| 51 | 51 |
```bash
|
| 52 | |
$ collage test
|
| 52 |
$ bricoleur test
|
| 53 | 53 |
testing my-document.md
|
| 54 | 54 |
- building source hello
|
| 55 | 55 |
- running "python main.py" in my-post/python-example
|
| 56 | 56 |
Hello, world
|
| 57 | 57 |
```
|
| 58 | 58 |
|
| 59 | |
we can also run `collage splice` to stitch the source code in question into our document:
|
| 59 |
we can also run `bricoleur splice` to stitch the source code in question into our document:
|
| 60 | 60 |
|
| 61 | 61 |
```bash
|
| 62 | |
$ collage splice
|
| 62 |
$ bricoleur splice
|
| 63 | 63 |
Here is a document describing a snippet of Python source. A 'Hello
|
| 64 | 64 |
World' program in Python looks like this:
|
| 65 | 65 |
|
|
| 72 | 72 |
|
| 73 | 73 |
# Including Multiple Source Files Per Project
|
| 74 | 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
|
| 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 `bricoleur` file could be updated to include
|
| 76 | 76 |
|
| 77 | 77 |
```
|
| 78 | 78 |
# ...
|
|
| 99 | 99 |
main()
|
| 100 | 100 |
```
|
| 101 | 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:
|
| 102 |
The two comment lines around the `main` function demarcate a _section_ of the file: `bricoleur` 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 `bricoleur` file to read:
|
| 103 | 103 |
|
| 104 | 104 |
```
|
| 105 | 105 |
# ...
|