Views

A view is a graph with a label and a description, which can be viewed in our web app

They can compared to Architectural views, however we aim to make them interactive and contain more and better information.

The cool thing about having architectural views in your CI pipeline, is that you have historical information, and that they are constantly up to date.

This is what you can use the codoc app for. You can see all prior versions, and how your system evolves from a structural perspective. It’s super cool in our humble opinion.

In our framework, we define a view as consisting of:

  • A graph

  • A label

  • A unique id

  • A project that (which owns the view)

  • An optional commit hash

View Functions

Views functions are functions that are used to generate views.

They should reside in files prefixed with views_ and reside inside a codoc_views folder in your root directory.

A simple example can be found in Your first view function.

A view is simply a function that takes a graph as input and returns the graph that you want to view. Here you add a label and a description and any related data that is relevant to you. The label is supplied in the view decorator, and the description is simply the docstring of the view function.

The label you supply to the decorator is the one that will be visualized on the webapp.

Advanced Usage

By default the view

Dynamic Descriptions

The view function can also take a string as input if you want a dynamic description, i.e based on the docstring of something else. This can make documentation more DRY:

from codoc.service import filters
from codoc.service.export import view
from codoc.service.parsing.node import get_description

import myproject

@view(
    label="Module View",
    description=get_description(myproject)
)
def view_modules(graph):
    return filters.exclude_functions(filters.exclude_classes(graph)

Custom ID

The way we identify whether two views are the same, but different versions, is by using a unique graph_id. We generate this based on the function and file name, which is a combination we hope is unique. You can, however, set this yourself, if you have concrete reasons for it. Don’t do this if you don’t know what you are doing, because it my create collisions, and make your documentation unusable.

from codoc.service import filters
from codoc.service.export import view

import myproject

@view(
    label="Module View",
    graph_id="my_very_long_and_unique_id"
)
def view_modules(graph):
    return filters.exclude_functions(filters.exclude_classes(graph)