Skip to content

Design

Jump to bottom
David Andersson edited this page Dec 15, 2022 · 1 revision

Below is a in-depth discussion of the high level architecture of the GitHub action.

Overview

The action primarily functionality is:

  • Interpret documentation stored in the docs directory
  • Interpret documentation stored on discourse
  • Compare the documentation state of the docs directory and on discourse to derive the changes that need to be made
  • Execute the changes

The following sections discuss each of those in more detail.

Interpret documentation stored in the docs directory

The docs directory is made up of directories and markdown files. The index.md file is a special file because the contents of this file are not part of the documentation. Instead, it is an optional file whose contents will be only posted to the index post for a charm on discourse.

The following attributes of the docs directories and its files and subdirectories have meaning:

  • The directory and file name determine:
    • the order they are displayed on the navigation table
    • For directories and empty files, the title of the grouping on the navigation table
  • The file and directory hierarchy determines the groupings. Each file and sub-directory within a directory is interpreted to be within the grouping associated with that directory.
  • The relative path to the docs directory determines the unique identifier for a grouping or page (broken into the hierarchy and replacing / with - for the relative path)
  • The first H1 or first line determines the title on the navigation table for files with content
  • The file content determines the content of a page

The code executing this is broken into:

  • A function that returns a sorted list of files and directories relevant for the documentation
  • A few functions that take a single path and calculate the hierarchy, title and navigation table path
  • A function that takes a single path and constructs a data structure with all the relevant information for a path
  • A function that gets the iterable with all the relevant files and directories and calls the function to extract all the relevant information for each file and directory

This means that each of the functions can be tested easily using parametrised tests.

Interpret documentation stored on discourse

The documentation is stored on discourse as an index topic which includes a navigation table that links to the other topics which contain the documentation shown to the user. The index topic may include content other than the navigation table which will be shown on discourse but not to the documentation reader. This content is often used to indicate to discourse users that the topic relates to the documentation for a charm.

The navigation table looks something like the following:

...

# Navigation

| level | path | navlink |
| -- | -- | -- |
| <level 1> | <path 1> | [<navlink title 1>](<navlink link 1>) |
...
| <level N> | <path N> | [<navlink title N>](<navlink link N>) |
  • level is similar to the hierarchy of the file. The larger the value, the more subordinated it is. The previous entry with a lower level indicates the parent which is a grouping (as indicated by navlink).
  • path is similar to the relative path of the file to the docs directory and is used to uniquely identify the row in combination with the level.
  • navlink indicates whether the item is a grouping (the link is empty) or a page (the link points to a page on discourse).

The code executing this is broken into:

  • A function that filters the lines of the table and determines whether they should be included based on a regular expression
  • A function that converts that line into a data structure
  • A function that gets the navigation table from the index page and uses the above function to convert to an iterable of a data structure that holds the information about the navigation table
Clone this wiki locally