Note: this project is on hold indefinitely. Discovering the excellent Dash app for OSX has greatly dampened my enthusiasm to continue working on it.
- Create useful developer reference material and make it available under a permissive license.
- Develop conventions that allow people to easily contribute to the library.
- Provide a tool to combine select material into a searchable, single-file reference document.
- Base functionality is coming along reasonably well. I would like to get some nicer sample templates done as well as provide more sample material.
- Lots of back and forth on some of the finer points of the YAML schema. I'd like to wrap this up ASAP and tweak later.
- YAML references (& and *) will be flattened in include/exclude sections to simplify files groups.
- Include spec: ^Python/shutil
Entries are a collection of one or two content elements and optional options array. If a two content blocks are provided, the first is considered the "key" and the second the "description". These are typically shown as two columns in the output. If a key is present, it can be used as part of the automatic URL generation.
Project/section division. How to handle packages, such as the bazillion in PyPy? Are they projects? (Probably) How to handle http://www.cpan.org/modules/01modules.index.html?
Sample file types (from Ack):
Good project organization is important both for people wanting to create or maintain material, and for those wanting to consume it. Developing a taxonomy for just about anything is difficult. Any structure will be a poor fit for some items, and people will have strong opinions on how to arrange things.
A Project is defined a folder that has the file
_project.yml in it. To be
useful that same folder will contain one or more section files (also YAML). The
name of the folder is not significant for the generated output, but it is
important for the maintainability of the Crutches project.
TBD: whether directories can be allowed to not have a
_project.yml file in it.
A single content string
Crutch uses Handlebars templates to generate the aggregate output. The parsing of the template goes roughly like:
- Load the template file specified by the configuration.
- Load scripts and stylesheets from the Assets directory. (Compilation will fail if they're not found.)
- Create an single HTML file that contains all .js and .css assets, reference card data assigned to a variable, the template assigned to a variable.
- When the file is loaded, the template is processed using the reference cards data as a context.
This application has most of the feature that I need, but there are few that I'm considering adding. As more people use the tool I'm sure this list will grow.
- Per section/item versions. It would be good if one could see only the reference material for a given version range.