First, Computer Words reads your config file, which tells it which Markdown files you want to include, and in what order. See Defining table of contents structure with file_hierarchy for details.

Then, each file is parsed into a tree, with a CWDocumentNode as the root. These document nodes are then added to a global CWRootNode.

Each node has a globally unique ID and a name (i.e. type, kind, label).

So this:

# Title

some text

# Part 2

text of part 2

becomes this:

This is all stored in a CWTree object, which allows you to access and mutate the tree in the next step.

Then we apply a processor library to the graph. A library is a mapping of node_name -> [processor]. A processor is a function process(tree, node) which mutates the tree in response to visiting node.

For example, here's a processor that reverses all text:

@library.processor('Text')
def reverse_text(tree, node):
    tree.replace_node(node, CWTextNode(node.text[::-1]))

The library is applied by traversing the tree in post-order (children before parents). That way, when a node is visited, its subtree is guaranteed to be complete.

If a processor mutates a child of its node, that node is marked "dirty". After each post-order traversal of the whole tree, if any nodes are dirty, the tree is traversed again, and only the dirty nodes' processors will be run.

Supported mutations are documented on class CWTree()src.

Once the processors have been run until there are no more dirty nodes, it's time to do something with the complete tree.

This is where a writer takes over. The job of a writer is to turn a CWTree into human-readable output of some kind.

The only writer available right now is the HTML writer. It works by defining a visitor for each node name, where each visitor writes the opening tag, visits its children, and then writes the closing tag.

Since few people will be writing writers, this is the least well documented part of Computer Words right now.