Yamldoc is a project mainly written in Ruby, based on the MIT license.
YAMLDoc documentation standard for YAML configuration files.
= YAMLDoc
YAMLDoc helps software developers design clean, understandable configuration files and generate tools for nontechnical users to edit them.
== 1. Philosophy Users should never be forced to edit a text file to configure software, but should always be able to exercise that option in a clear and usable way.
Proper configuration file design is a highly overlooked aspect of software engineering.
== 2. Purpose
YAMLDoc is a documentation specification that helps you document YAML* software configuration files in a way that is nice to read in plain text, yet structured enough to be automatically extracted and processed by a machine.
Documenting your configuration files in this way grants you the ability to generate interactive editors and GUI forms to help nontechnical users get your software up and running quickly, and helps eliminate guesswork which leads to invalid directive values creating unexpected program state.
YAMLDoc borrows heavily from TomDoc*.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119*.
== 3. Components
== 4. Getting Started
A YAMLDoc file is a YAML example file with the filename format "NAME.example.yml.", with an optional extension to signal interpreted code to a preprocessor (for example, "application.example.yml.erb").
The example file MUST contain every node expected by the application, and SHOULD provide sane default values for all nodes.
The example file SHOULD be checked into your version-control system, and MUST NOT ever be read into your application itself.
When your application is deployed, this file MUST be copied to the same directory with the ".example" extension omitted. This copy is the file to be read into your application, and MUST NOT be checked into your VCS.
If you are using an automated installation or deployment script, the file SHOULD be copied automatically and an editor presented to the user, unless the default values therein are likely to be valid on a majority of systems.
A user MUST NOT edit the example file.
== 5. Maintaining compatibility
Any time a node is added to, changed or removed from the application, the developer MUST also modify this node accordingly in the example file. The YAMLDoc tool MAY then be used to quickly update his personal copy.
A warning MAY be raised by the application when a version difference is detected between the example and deployed YAML files. This MAY also cause a unit test to fail when the test suite is run.
== 6. Specification
YAMLDoc content must be contained in a document. That is, YAMLDoc SHALL be ignored by the parser before "---" and after "...".
Every node MUST be documented with YAMLDoc. Undocumented nodes are not permitted.
A YAMLDoc block consists of a block of single comment markers (#) that appear directly above the node. Lines SHOULD be wrapped at 80 characters. Lines that contain text MUST be separated from the comment marker by a single space. Lines that do not contain text SHOULD consist of just a comment marker (no trailing spaces).
Example 6.1
application_name: Hello World ...
A YAMLDoc block contains two sections; a Description, followed by either Choices or Format, but not both. Only a description is required.
==== 6.1 The Description Section
The description section SHOULD be in plain sentences. Each sentence SHOULD end with a period. Good descriptions explain what the setting does at a high level. Make sure to explain any pitfalls that the user may experience. Lines SHOULD be wrapped at 80 characters.
==== 6.2 The Choices Section
A node with a limited set of valid choices MUST document these choices in standard YAML inside the YAMLDoc comment block. This block is started with the "Choose" keyword (case-sensitive), optionally followed by the number of choices allowed (as an Integer or Ruby range), then a colon, followed by a YAML sequence. This YAML sequence MAY be on the same line as the Choose keyword.
Example 6.2
preferred_fruits: ['oranges', 'bananas']
favorite_fruit: apples
The allowed choices MAY reference a sequence defined earlier in the document.
Example 6.3
&types_of_fruit:
bananas
preferred_fruits: ['oranges', 'bananas']
==== 6.3 The Format Section
A node with a scalar value that MUST match a particular format can be validated with a Ruby-compatible regular expression.
Example 6.4
admin_email: [email protected]
== References
== Contributing to YAMLDoc
== Copyright
Copyright (c) 2011 Logan Koester. See LICENSE.txt for further details.