Improve documentation appearance

.github/workflows/docs.yml

@@ -53,7 +53,7 @@ jobs:
       - name: Build files
         shell: bash
         run: |
-          pip3 install sphinx sphinx_rtd_theme
+          pip3 install sphinx furo
           unzip Simba-Win32.zip
           ./Simba-Win32.exe --run "DocGen/docgen.simba"
 

DocGen/docgen.simba

@@ -1,8 +1,35 @@
 // To run to locally build docs you need:
 //
-// 1) Python installed, on PATH too so Simba can execute "Python"
-// 2) "sphinx" and "sphinx_rtd_theme" installed:
-//      pip3 install sphinx sphinx_rtd_theme
+// 1) Python installed which is on the systems PATH too so Simba can execute "Python"
+// 2) "sphinx" and "furo" installed: pip3 install sphinx furo
+
+// Notes:
+//
+// The theme used is furo > https://pradyunsg.me/furo/quickstart/
+//
+// This script extracts comments from `SourceFiles` and adds them to .rst files,
+// where sphinx generates static html files.
+//
+// This script also parsers some more prettier syntax such as:
+//
+// - Triple backtick -> .. code-block::
+// - Single backtick -> :code:
+// - Greater than (at the beginning of line) -> .. code-block::
+//
+// Example documentation comment:
+
+(*
+SomeMethod
+~~~~~~~~~~
+> procedure SomeMethod(SomeInt: Integer);
+
+This method does something.
+Use it like:
+
+```
+SomeMethod(123)
+```
+*)
 
 var
   SourceFiles: array of record
@@ -53,30 +80,51 @@ from datetime import datetime
 project = 'Simba'
 author = 'Simba'
 copyright = str(datetime.now().year) + ', Simba'
-templates_path = ['.']
-pygments_style='sphinx'
 source_suffix = '.rst'
 master_doc = 'index'
 highlight_language = 'pascal'
-html_favicon = '../images/simba.png'
-html_theme = 'sphinx_rtd_theme'
+html_title = 'Simba'
+html_favicon = '../images/icon.ico'
+html_theme = 'furo'
+html_css_files = ['../custom.css'] # relative to `_static` dir
 extensions = [
     'sphinx.ext.githubpages',
-]
-";
+]";
+
+
+CSS_OVERRIDES = "
+  body:not([data-theme="+'"light"'+"]) .highlight .nc {
+	  text-decoration: none;
+  }
+  body:not([data-theme="+'"dark"'+"]) .highlight .nc {
+	  text-decoration: none;
+  }
 
-  TEMPLATE_FILE = "
-{% extends '!layout.html' %}
-  {% block footer %} {{ super() }}
-  <style>
-         .wy-nav-content { min-width: 85%; }
-  </style>
-{% endblock %}";
+  h1 {
+	  font-size: 1.75em;
+  }
+  h2 {
+	  font-size: 1em;
+  }
+*)
+";
 
   TOC_FILE = "
-Welcome to Simba documentation
-******************************
+Simba
+=====
+
 .. toctree::
+   :hidden:
+
+   api/index
+";
+
+  TOC_FILE_TEST = "
+API documentation
+=================
+
+.. toctree::
+   :hidden:
 
 ";
 
@@ -140,8 +188,8 @@ end;
 // Header to code block
 {
 Test
-****
-procedure Test;
+~~~~
+> procedure Test;
 }
 procedure MakeCodeHeaders(var Str: String);
 var
@@ -186,8 +234,8 @@ begin
     Comments := Comments.Replace('Note::', '.. note::');
     Comments := Comments.Replace('Warning::', '.. warning::');
 
-    FileWrite(INPUT_DIR + Name + '.rst', Comments);
-    FileAppend(INPUT_DIR + 'index.rst', '   ' + Name + LINE_SEP);
+    FileWrite(INPUT_DIR + 'api/' + Name + '.rst', Comments);
+    FileAppend(INPUT_DIR + '/api/index.rst', '   ' + Name + LINE_SEP);
   end;
 end;
 
@@ -204,7 +252,10 @@ begin
 
   FileWrite(INPUT_DIR + 'index.rst', TOC_FILE);
   FileWrite(INPUT_DIR + 'conf.py', CONFIG_FILE);
-  FileWrite(INPUT_DIR + 'layout.html', TEMPLATE_FILE);
+  FileWrite(OUTPUT_DIR + 'custom.css', CSS_OVERRIDES);
+
+  DirCreate(INPUT_DIR + '/api');
+  FileWrite(INPUT_DIR + '/api/index.rst', TOC_FILE_TEST);
 
   for I := 0 to High(SourceFiles) do
     ParseComments(SourceFiles[I].FileName, SourceFiles[I].Title);

Source/editor/simba.editor_autocomplete.pas

@@ -341,16 +341,20 @@ procedure TSimbaAutoComplete.DoCodeCompletion(var Value: String; SourceValue: St
 var
   Decl: TDeclaration;
 begin
-  Decl := FFilteredDecls[Position];
-  if Decl.IsName(SourceValue) then
-    Value := SourceValue
+  Decl := GetDecl(Position);
+  if (Decl <> nil) then
+    if Decl.IsName(SourceValue) then
+      Value := SourceValue
+    else
+      Value := Decl.Name
   else
-    Value := Decl.Name;
+    Value := SourceValue;
+
   Value := Value + KeyChar;
 
   case KeyChar of
-    '.': Application.QueueAsyncCall(@ContinueCompletion, TSimbaEditor(Editor).AutoComplete.AutoCompleteCommand);
-    ',','(': Application.QueueAsyncCall(@ContinueCompletion, TSimbaEditor(Editor).ParamHint.ParamHintCommand);
+    '.':      Application.QueueAsyncCall(@ContinueCompletion, TSimbaEditor(Editor).AutoComplete.AutoCompleteCommand);
+    ',', '(': Application.QueueAsyncCall(@ContinueCompletion, TSimbaEditor(Editor).ParamHint.ParamHintCommand);
   end;
 end;
 

Source/script/imports/simba/simba.import_variant.pas

@@ -26,6 +26,31 @@ implementation
 Variant
 =======
 The variant "magic" datatype can store most base types.
+
+```
+var v: Variant;
+begin
+  WriteLn('Should be unassigned: ', v = Variant.UnAssigned);
+  v := 'I am a string';
+  Writeln('Now should *not* be unassigned: ', v = Variant.Unassigned);
+  WriteLn('And should be string:');
+  WriteLn(v.VarType, ' -> ', v);
+  v := 123;
+  WriteLn('Now should be integer:');
+  WriteLn(v.VarType, ' -> ', v);
+end;
+```
+
+Note:: If curious to how the Variant datatype works, internally it's a record:
+
+  ```
+  // pseudo code
+  type
+    InternalVariantData = record
+      VarType: EVariantType;
+      Value: array[0..SizeOf(LargestDataTypeVariantCanStore)] of Byte;
+    end;
+  ```
 *)
 
 type
@@ -51,6 +76,9 @@ procedure _LapeVariantVarType(const Params: PParamArray; const Result: Pointer);
   function GetVarType(const v: Variant): EVariantType;
   begin
     case VarType(v) of
+      varEmpty:    Result := EVariantType.Unassigned;
+      varNull:     Result := EVariantType.Null;
+
       varBoolean:  Result := EVariantType.Boolean;
 
       varShortInt: Result := EVariantType.Int8;
@@ -71,6 +99,8 @@ procedure _LapeVariantVarType(const Params: PParamArray; const Result: Pointer);
       varOleStr:   Result := EVariantType.WString;
       varUString:  Result := EVariantType.UString;
       varString:   Result := EVariantType.AString;
+
+      varVariant:  Result := EVariantType.Variant;
       else
         Result := EVariantType.Unknown;
     end;
@@ -84,10 +114,12 @@ procedure _LapeVariantVarType(const Params: PParamArray; const Result: Pointer);
 Variant.IsNumeric
 ~~~~~~~~~~~~~~~~~
 > function Variant.IsNumeric: Boolean;
+
+Is integer or float?
 *)
 procedure _LapeVariantIsNumeric(const Params: PParamArray; const Result: Pointer); LAPE_WRAPPER_CALLING_CONV
 begin
-  PEvalBool(Result)^ := VarIsNumeric(PVariant(Params^[0])^);
+  PBoolean(Result)^ := VarIsNumeric(PVariant(Params^[0])^);
 end;
 
 (*
@@ -97,17 +129,17 @@ procedure _LapeVariantIsNumeric(const Params: PParamArray; const Result: Pointer
 *)
 procedure _LapeVariantIsString(const Params: PParamArray; const Result: Pointer); LAPE_WRAPPER_CALLING_CONV
 begin
-  PEvalBool(Result)^ := VarIsStr(PVariant(Params^[0])^);
+  PBoolean(Result)^ := VarIsStr(PVariant(Params^[0])^);
 end;
 
 (*
-Variant.IsOrdinal
+Variant.IsInteger
 ~~~~~~~~~~~~~~~~~
-> function Variant.IsOrdinal: Boolean;
+> function Variant.IsInteger: Boolean;
 *)
-procedure _LapeVariantIsOrdinal(const Params: PParamArray; const Result: Pointer); LAPE_WRAPPER_CALLING_CONV
+procedure _LapeVariantIsInteger(const Params: PParamArray; const Result: Pointer); LAPE_WRAPPER_CALLING_CONV
 begin
-  PEvalBool(Result)^ := VarIsOrdinal(PVariant(Params^[0])^);
+  PBoolean(Result)^ := VarIsOrdinal(PVariant(Params^[0])^);
 end;
 
 (*
@@ -117,7 +149,7 @@ procedure _LapeVariantIsOrdinal(const Params: PParamArray; const Result: Pointer
 *)
 procedure _LapeVariantIsFloat(const Params: PParamArray; const Result: Pointer); LAPE_WRAPPER_CALLING_CONV
 begin
-  PEvalBool(Result)^ := VarIsFloat(PVariant(Params^[0])^);
+  PBoolean(Result)^ := VarIsFloat(PVariant(Params^[0])^);
 end;
 
 (*
@@ -127,7 +159,39 @@ procedure _LapeVariantIsFloat(const Params: PParamArray; const Result: Pointer);
 *)
 procedure _LapeVariantIsBoolean(const Params: PParamArray; const Result: Pointer); LAPE_WRAPPER_CALLING_CONV
 begin
-  PEvalBool(Result)^ := VarIsBool(PVariant(Params^[0])^);
+  PBoolean(Result)^ := VarIsBool(PVariant(Params^[0])^);
+end;
+
+(*
+Variant.IsVariant
+~~~~~~~~~~~~~~~~~
+> function Variant.IsVariant: Boolean;
+
+The variant holds another variant!
+*)
+procedure _LapeVariantIsVariant(const Params: PParamArray; const Result: Pointer); LAPE_WRAPPER_CALLING_CONV
+begin
+  PBoolean(Result)^ := VarIsType(PVariant(Params^[0])^, varVariant);
+end;
+
+(*
+Variant.IsUnAssigned
+~~~~~~~~~~~~~~~~~~~~
+> function Variant.IsUnAssigned: Boolean;
+*)
+procedure _LapeVariantIsUnAssigned(const Params: PParamArray; const Result: Pointer); LAPE_WRAPPER_CALLING_CONV
+begin
+  PBoolean(Result)^ := VarIsClear(PVariant(Params^[0])^);
+end;
+
+(*
+Variant.IsNull
+~~~~~~~~~~~~~~
+> function Variant.IsNull: Boolean;
+*)
+procedure _LapeVariantIsNull(const Params: PParamArray; const Result: Pointer); LAPE_WRAPPER_CALLING_CONV
+begin
+  PBoolean(Result)^ := VarIsNull(PVariant(Params^[0])^);
 end;
 
 (*
@@ -176,11 +240,15 @@ procedure ImportVariant(Compiler: TSimbaScript_Compiler);
     addGlobalType('enum(Unknown, Unassigned, Null, Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64, Single, Double, DateTime, Currency, Boolean, Variant, AString, UString, WString)', 'EVariantVarType');
 
     addGlobalFunc('function Variant.VarType: EVariantVarType;', @_LapeVariantVarType);
+
     addGlobalFunc('function Variant.IsNumeric: Boolean;', @_LapeVariantIsNumeric);
-    addGlobalFunc('function Variant.IsString: Boolean;', @_LapeVariantIsString);
-    addGlobalFunc('function Variant.IsOrdinal: Boolean;', @_LapeVariantIsOrdinal);
+    addGlobalFunc('function Variant.IsInteger: Boolean;', @_LapeVariantIsInteger);
     addGlobalFunc('function Variant.IsFloat: Boolean;', @_LapeVariantIsFloat);
+    addGlobalFunc('function Variant.IsString: Boolean;', @_LapeVariantIsString);
     addGlobalFunc('function Variant.IsBoolean: Boolean;', @_LapeVariantIsBoolean);
+    addGlobalFunc('function Variant.IsVariant: Boolean;', @_LapeVariantIsVariant);
+    addGlobalFunc('function Variant.IsUnAssigned: Variant; static;', @_LapeVariantIsUnAssigned);
+    addGlobalFunc('function Variant.IsNull: Variant; static;', @_LapeVariantIsNull);
 
     addGlobalFunc('function Variant.Null: Variant; static;', @_LapeVariantNull);
     addGlobalFunc('function Variant.Unassigned: Variant; static;', @_LapeVariantUnassigned);
@@ -189,4 +257,4 @@ procedure ImportVariant(Compiler: TSimbaScript_Compiler);
   end;
 end;
 
-end.
+end.