Global Options

Sometimes a useful attribute about a need can be derived rather than explicitly stated in the RST.

In our use case, we have a separate project that implements scripts that validate the requirement against some vendors implementation of the spec. We’d like to keep track of which requirements have validation scripts written, but we’d also prefer not to have to keep track of this information in both the requirements project and the validation project. The validation project already tracks traceability to the requirements in an usable data format such as YAML.

It would be nice if we could add derived metadata to a requirement that a script exists and provide a link to that particular script.

The idea I thought would be useful would be being able to specify dynamic attributes in the conf.py file, and map them to some callable that could derive the value at build time.

Perhaps something like this in conf.py:

# Instantiate some object that can look up the information.
# In a more simple example, it could map to a single function

repos = ValidationRepository('some config to get the data')

needs_dynamic_options = {
   'validated' : repos.is_validated,
   'validation_link': repos.get_link,
}

These callables could be invoked and be passed the app environment and the need_info during the build, and then derive additional attributes. This derivation could make use of external resources or just other attributes in need_info.

Technically a single callable could return a dict that gets merged, but I’m thinking it’s better to be explicit about the values.

The downside here is this attribute only gets created at build time, but at least in our case we could have our CI builds could trigger the documentation build whenever it’s updated.

I could also see a use case for a JavaScript method to get the value, but that would only be available to HTML builders and would probably be more complicated to implement.

[danwos]

Implemented in 0.3.0

[tlovett]

That works. Thanks.