docgen.simba

// To run to locally build docs you need:
//
// 1) Python installed which is on the systems PATH too so Simba can execute "Python"
// 2) "sphinx" and "furo" installed: pip3 install sphinx furo myst-parser

// Notes:
// - The theme used is furo > https://pradyunsg.me/furo/quickstart/
// - This script extracts documentation comments from `APIFiles` into .rst files
//   where sphinx generates static html files.

// Example documentation comment:

(*
SomeMethod
----------
> procedure SomeMethod(SomeInt: Integer);

This method does something.
Use it like:

```
SomeMethod(123);
```
*)

var
  APIFiles: array of record
    FileName: String;
    Name: String;
  end;

begin
  APIFiles += ['Source\script\imports\simba.import_base.pas',          'Base'           ];
  APIFiles += ['Source\script\imports\simba.import_colormath.pas',     'Color Math'     ];
  APIFiles += ['Source\script\imports\simba.import_point.pas',         'TPoint'         ];
  APIFiles += ['Source\script\imports\simba.import_tpa.pas',           'TPointArray'    ];
  APIFiles += ['Source\script\imports\simba.import_atpa.pas',          'T2DPointArray'  ];
  APIFiles += ['Source\script\imports\simba.import_box.pas',           'TBox'           ];
  APIFiles += ['Source\script\imports\simba.import_boxarray.pas',      'TBoxArray'      ];
  APIFiles += ['Source\script\imports\simba.import_quad.pas',          'TQuad'          ];
  APIFiles += ['Source\script\imports\simba.import_circle.pas',        'TCircle'        ];
  APIFiles += ['Source\script\imports\simba.import_windowhandle.pas',  'TWindowHandle'  ];
  APIFiles += ['Source\script\imports\simba.import_debugimage.pas',    'Debug Image'    ];
  APIFiles += ['Source\script\imports\simba.import_random.pas',        'Random'         ];
  APIFiles += ['Source\script\imports\simba.import_target.pas',        'Target'         ];
  APIFiles += ['Source\script\imports\simba.import_web.pas',           'Web'            ];
  APIFiles += ['Source\script\imports\simba.import_file.pas',          'File'           ];
  APIFiles += ['Source\script\imports\simba.import_encoding.pas',      'Encoding'       ];
  APIFiles += ['Source\script\imports\simba.import_timing.pas',        'Timing'         ];
  APIFiles += ['Source\script\imports\simba.import_string.pas',        'String'         ];
  APIFiles += ['Source\script\imports\simba.import_process.pas',       'Process'        ];
  APIFiles += ['Source\script\imports\simba.import_math.pas',          'Math'           ];
  APIFiles += ['Source\script\imports\simba.import_matchtemplate.pas', 'Match Template' ];
  APIFiles += ['Source\script\imports\simba.import_misc.pas',          'Misc'           ];
  APIFiles += ['Source\script\imports\simba.import_matrix.pas',        'Matrix'         ];
  APIFiles += ['Source\script\imports\simba.import_json.pas',          'JSON'           ];
  APIFiles += ['Source\script\imports\simba.import_image.pas',         'Image'          ];
  APIFiles += ['Source\script\imports\simba.import_dtm.pas',           'DTM'            ];
  APIFiles += ['Source\script\imports\simba.import_async.pas',         'ASync'          ];
end;

procedure H2ToH3(Dir: String);
var
  FileName: String;
begin
  for FileName in DirList(Dir) do
    FileWrite(FileName, FileRead(FileName).Replace('h2', 'h3', [rfReplaceAll]));
end;

// The one non sphinx/markdown we change is this:
//  - Change lines that begin with '> ' to codeblocks.
procedure RightArrowToCodeBlock(var Str: String);
var
  I: Integer;
  Lines: TStringArray;
begin
  Lines := Str.SplitLines;
  while (I < Length(Lines)) do
  begin
    if Lines[I].StartsWith('> ') then
    begin
      Lines[I].Delete(1, 2);
      Lines.Insert('```', I);
      Lines.Insert('```', I+2);

      Inc(I, 2);
    end;

    Inc(I);
  end;

  Str := LINE_SEP.Join(Lines);
end;

// Delete old api generation
procedure CleanAPI;
var
  FileName: String;
begin
  for FileName in DirList('DocGen/source/api/') do
    if (not (PathExtractName(FileName) in ['index.rst'])) then
      FileDelete(FileName);
end;

procedure BuildAPI;

  function BuildFile(FileName, Name: String): Boolean;
  var
    Comment, Comments: String;
  begin
    if not FileExists(FileName) then
    begin
      WriteLn('API file "', FileName, '" does not exist');
      Exit;
    end;

    for Comment in FileRead(FileName).BetweenAll('(*', '*)') do
    begin
      if (Comments <> '') then
        Comments += LINE_SEP + '----' + LINE_SEP;
      Comments += Comment;
    end;

    Result := Length(Comments) > 0;
    if Result then
    begin
      RightArrowToCodeBlock(Comments);

      FileWrite('DocGen/source/api/' + Name + '.md', Comments);
    end;
  end;

var
  I: Integer;
begin
  for I := 0 to High(APIFiles) do
    BuildFile(APIFiles[I].FileName, APIFiles[I].Name);
end;

var
  SphinxOutput: String;
begin
  ClearSimbaOutput();

  CleanAPI();
  BuildAPI();

  WriteLn('Sphinx exit code: ', RunCommand('sphinx-build', ['-q', '-E', 'DocGen/source', 'DocGen/build'], SphinxOutput));
  if (SphinxOutput <> '') then
    WriteLn(SphinxOutput);

  WriteLn('Link: "' + PathNormalize('DocGen/build/index.html') + '"');

  // looks better like this, imo
  H2ToH3('DocGen/build/api');
end.