Encodings

Generates a section with one section for each file included in the root file.

Each section will include the encoding where comments are rendered as markdown. This means that any markdown code can be rendered, including sections, admonitions, code, etc.

Commented clingo code

If a comment can be interpreted by clingo as a valid statement, it will be ignored.

Output Usage

Will skip the next comment

    c:-d,e.

The next line prints a line separator

---

The following lines will not be printed and can use in the encodings as separator

    % Will skip the next comment since it is parsable
    % a:-b.
    %% This is also skipped since it is a comment in clingo
    c:-d,e.
    % The next line prints a line separator
    %----------------------
    % The following lines will not be printed and can use in the encodings to separate sections
    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    %%=================================
    %%---------------------------------

Markdown headers

When using # for markdown headers, make sure there is no trailing space between the clingo comment % and the #.

    % # Incorrect title
    %# Correct title

For each encoding, a section in the table of content will be created.

Example

Output Usage

Encodings

examples/sudoku/encoding.lp

Source

%# Sudoku Puzzle
%   Uses the well known [puzzle](https://en.wikipedia.org/wiki/Sudoku)
%

#const dim = 3.
val(1..dim*dim).
pos(X,Y) :- val(X), val(Y).

%*! sudoku(X,Y,V)

Describes a sudoku board. The value of cell (X,Y) is V.

Args:
    - X: the row of the cell
    - Y: the column of the cell
    - V: the value of the cell
*%

%*! initial(X,Y,V)

Describes initial values of the sudoku board. The value of cell (X,Y) is V.

Args:
    - X: the row of the cell
    - Y: the column of the cell
    - V: the value of the cell
*%

%*! pos(X,Y)

Describes a cell (X,Y) in the sudoku board.

Args:
    - X: the row of the cell
    - Y: the column of the cell
*%

%*! val(V)

Describes a possible value V for a cell.

Args:
    - V: the value
*%


subgrid(X,Y,(((X-1)/dim)*dim+((Y-1)/dim))) :- pos(X,Y).

% A choice rule for each cell
1 { sudoku(X,Y,V) : val(V) } 1 :- pos(X,Y).

%## Constraints
:- sudoku(X,Y,V), sudoku(X',Y,V), X != X'.
:- sudoku(X,Y,V), sudoku(X,Y',V), Y != Y'.
:- sudoku(X,Y,V), sudoku(X',Y',V), subgrid(X,Y,S), subgrid(X',Y',S), (X,Y)!=(X',Y').

sudoku(X,Y,V) :- initial(X,Y,V).

%## Shows

#show .
#show sudoku/3.

Encoding

Sudoku Puzzle

Uses the well known puzzle

val(1..dim*dim).
pos(X,Y) :- val(X), val(Y).
subgrid(X,Y,(((X-1)/dim)*dim+((Y-1)/dim))) :- pos(X,Y).

A choice rule for each cell

1 { sudoku(X,Y,V) : val(V) } 1 :- pos(X,Y).

Constraints

:- sudoku(X,Y,V), sudoku(X',Y,V), X != X'.
:- sudoku(X,Y,V), sudoku(X,Y',V), Y != Y'.
:- sudoku(X,Y,V), sudoku(X',Y',V), subgrid(X,Y,S), subgrid(X',Y',S), (X,Y)!=(X',Y').
sudoku(X,Y,V) :- initial(X,Y,V).

Shows

#show .
#show sudoku/3.

::: examples/sudoku/encoding.lp
    handler: asp
    options:
        encodings:
            source: true
        start_level: 3

Notice the use of start_level passed for rendering headers and the TOC.

Configuration options

The option encodings can be further customized with the following options:

• source Boolean indicating if the full source code should be included as a standalone code block. Defaults to False.
• git_link Boolean indicating if a repository link should be added in the encoding title. Defaults to False (requires repo_url, usually taken from mkdocs.yml).

Example

Output Usage

Encodings

examples/sudoku/encoding.lp

Encoding

Sudoku Puzzle

Uses the well known puzzle

val(1..dim*dim).
pos(X,Y) :- val(X), val(Y).
subgrid(X,Y,(((X-1)/dim)*dim+((Y-1)/dim))) :- pos(X,Y).

A choice rule for each cell

1 { sudoku(X,Y,V) : val(V) } 1 :- pos(X,Y).

Constraints

:- sudoku(X,Y,V), sudoku(X',Y,V), X != X'.
:- sudoku(X,Y,V), sudoku(X,Y',V), Y != Y'.
:- sudoku(X,Y,V), sudoku(X',Y',V), subgrid(X,Y,S), subgrid(X',Y',S), (X,Y)!=(X',Y').
sudoku(X,Y,V) :- initial(X,Y,V).

Shows

#show .
#show sudoku/3.

::: examples/sudoku/encoding.lp
    handler: asp
    options:
        encodings:
            git_link: true
            source: false
        start_level: 3