Docs

Overview

This chapter provides guidance on how to use the reference documentation. Each section used in the documentation is described below.

Index

The main index page is composed of the following sections:

Entities

This section lists each of the entity base terms. This includes the primary four entity types: site, space, equip, and point. Each term links to a taxonomy tree for the term's subtypes. You can add new entity terms into this section with the docTaxonomy marker.

Taxonomies

This section lists key terms with a link to an index of the term's subtype tree. You can add new terms into this section with the docTaxonomy tag (if the term is an entity, it will go into the entities section).

Appendix

This section contains links to miscellaneous listing pages. Some of the appendices include:

  • conjuncts: all terms composed of multiple tags
  • tags: all terms composed of an atomic name
  • terms: all tags and conjuncts listed together
  • lib: listing of library modules
  • filetype: listing of Haystack filetype encodings

Terms

Section within a lib index that lists the terms defined by the lib module.

Manuals

Manuals are hand written documents that provide design details to augment the auto-generated reference documentation. Manuals are composed of chapters which correspond to individual HTML pages.

A manual index is composed of two sections:

  • manual: summary information including name and brief overview
  • chapters: index of the manual's chapter pages

Defs

Each def has its own reference page in the documentation composed of the following sections:

Def

The def section contains summary information for the definition including its identifier formatted doc description.

Conjunct

This section is used only for conjuncts. It provides a link to the definition of each of the conjunct's parts.

Meta

The meta section documents the normalized tags for the definition's representation as a dict. Each tag present in the definition is listed here, although some values such as the doc or enum may reference another section.

Usage

This section is used only on entity terms. It lists the required marker tags which must be applied to a dict to correctly implement the term. It takes into account conjuncts and supertypes with the mandatory marker.

Enum

If the definition has the enum tag then this section provides a listing of the documented enumerations and their summary.

Supertypes

This section lists the term's supertypes. The supertypes are organized as an indented tree down from most general to most specific. The first item is the root type, which is typically marker or val. The last item will be the definition's declared supertype matching the is tag. If the term has multiple supertypes then this tree will have multiple leaves.

Subtypes

This section lists the term's subtypes. The subtypes are organized in an indented tree structure.

Tags

This section lists the value tags associated with the entity via the tagOn association. This section also includes tags which are registered on the entity's supertypes.

UsedBy

This section lists terms which use the given association. Its provides a nice mechanism to cross-reference usage of association tags.

Children

This section lists children prototypes which are "contained" by the given entity type.

Protos

Prototypes are dict instances which model a predefined collection of tags.

Proto

The proto section defines the prototypes tags.

Implements

The definitions implemented by the prototype.