Added action to Premake scripts to check for and generate missing doc…

…umentation

- Added auto-generated documentation files for APIs without docs
- Renamed editAndContinue.md to editandcontinue.md to match convention

.github/workflows/ci-workflow.yml

@@ -16,6 +16,8 @@ jobs:
       run: make -f Bootstrap.mak linux PLATFORM=${{ matrix.platform }} CONFIG=${{ matrix.config }}
     - name: Test
       run: bin/${{ matrix.config }}/premake5 test --test-all
+    - name: Docs check
+      run: bin/${{ matrix.config }}/premake5 docs-check
     - name: Upload Artifacts
       if: matrix.config == 'release'
       uses: actions/upload-artifact@v2
@@ -35,6 +37,8 @@ jobs:
       run: make -f Bootstrap.mak macosx PLATFORM=${{ matrix.platform }} CONFIG=${{ matrix.config }}
     - name: Test
       run: bin/${{ matrix.config }}/premake5 test --test-all
+    - name: Docs check
+      run: bin/${{ matrix.config }}/premake5 docs-check
     - name: Upload Artifacts
       if: matrix.config == 'release'
       uses: actions/upload-artifact@v2
@@ -58,6 +62,9 @@ jobs:
     - name: Test
       run: bin\${{ matrix.config }}\premake5 test --test-all
       shell: cmd
+    - name: Docs check
+      run: bin\${{ matrix.config }}\premake5 docs-check
+      shell: cmd
     - name: Upload Artifacts
       if: matrix.config == 'release'
       uses: actions/upload-artifact@v2

premake5.lua

@@ -40,6 +40,106 @@
 	}
 
 
+	newaction {
+		trigger = "docs-check",
+		description = "Checks for missing documentation files and generates them",
+		execute = function ()
+			local count = 0
+			for k,v in pairs(premake.field._loweredList) do
+				local docfilepath = "website/docs/" .. k .. ".md"
+				local exists = os.isfile(docfilepath)
+				if not exists then
+					print("Genearting documenetation file for: ", k)
+					count = count + 1
+
+					-- Create doc file
+					local docfile = io.open(docfilepath, "w")
+					docfile:write(k)
+					docfile:write(" - This page was auto-generated. Feel free to help us improve the documentation by creating a pull request.\n\n")
+					docfile:write("```lua\n")
+					docfile:write(k .. " (value)\n")
+					docfile:write("```\n\n")
+					docfile:write("### Parameters ###\n\n")
+					if type(v.allowed) == "table" then
+						docfile:write("`value` is one of:\n\n")
+						for _,value in ipairs(v.allowed) do
+							docfile:write("* `" .. value .. "`: needs documentation\n")
+						end
+						docfile:write("\n")
+					else
+						docfile:write("`value` - needs documentation.\n\n")
+					end
+					docfile:write("## Applies To ###\n\n")
+					if #v.scopes == 1 then
+						docfile:write("The `" .. v.scope .. "` scope.\n\n")
+					else
+						docfile:write("The ")
+						for i,scope in ipairs(v.scopes) do
+							if i > 1 then
+								docfile:write(", ")
+							end
+							docfile:write("`" .. scope .. "`")
+						end
+						docfile:write(" scopes.\n\n")
+					end
+					docfile:write("### Availability ###\n\n")
+					-- Get git commits that contains API registration
+					local gitlog = "git log origin/master -S\"name = \\\"" .. k .. "\\\"\" --source --reverse --pretty=format:\"%h\""
+					-- Override path.normalize so it stops mangling our commands!
+					local pathnormalize = path.normalize
+					path.normalize = function (v) return v end
+					local stage = ""
+					local requiredversion = 0
+					local commits = os.outputof(gitlog)
+					local tags = ""
+					if commits ~= nil and commits ~= "" then
+						local commit = string.explode(commits, "\n")[1]
+						-- Get git tags that contain first commits
+						tags = os.outputof("git tag --contains " .. commit)
+					end
+
+					-- Get latest tag if commit hasn't been tagged yet
+					if tags == nil or tags == "" then
+						tags = os.outputof("git tag --sort=-creatordate")
+					end
+					local tag = string.explode(tags, "\n")[1]
+					-- tag should be in the format of `v5.0.0-alphaXX` where XX is the alpha version
+					local subversion = string.explode(tag, "-")[2]
+					-- subversion may be nil if there's no tags checked out
+					if subversion ~= nil then
+						if subversion:startswith("alpha") then
+							stage = "alpha"
+						elseif subversion:startswith("beta") then
+							stage = "beta"
+						end
+						subversion = subversion:sub(stage:len() + 1)
+						requiredversion = tonumber(subversion) + 1
+						-- There was no alpha17, instead specify beta1
+						if stage == "alpha" and requiredversion == 17 then
+							stage = "beta"
+							requiredversion = 1
+						end
+						docfile:write("Premake 5.0.0 " .. stage .. " " .. requiredversion .. " or later.\n\n")
+					else
+						docfile:write("Premake 5.0.0 unknown or later.\n\n")
+					end
+					path.normalize = pathnormalize
+					docfile:write("### Examples ###\n\n")
+					docfile:write("```lua\n")
+					docfile:write(k .. " (value)\n")
+					docfile:write("```\n\n")
+					docfile:write("<!-- This optional section should contain a list of links to any relevant pages.\n")
+					docfile:write("### See Also ###\n\n")
+					docfile:write("* [Another Page](anotherpage.md)\n")
+					docfile:write("-->\n\n")
+					docfile:close()
+				end
+			end
+			os.exit(count)
+		end
+	}
+
+
 	newaction {
 		trigger = "test",
 		description = "Run the automated test suite",

website/docs/Migrating-From-4.x.md

@@ -19,6 +19,6 @@ Many of the old [`flags`](flags.md) have become full-fledged functions. This sho
 | `FloatFast`, `FloatStrict` | [`floatingpoint`](floatingpoint.md) |
 | `Managed`, `Unsafe` | [`clr`](clr.md) |
 | `NativeWChar` | [`nativewchar`](nativewchar.md) |
-| `NoEditAndContinue` | [`editandcontinue`](editAndContinue.md) |
+| `NoEditAndContinue` | [`editandcontinue`](editandcontinue.md) |
 | `NoRTTI` | [`rtti`](rtti.md) |
 | `OptimizeSize`, `OptimizeSpeed` | [`optimize`](optimize.md) |

website/docs/Project-API.md

@@ -69,7 +69,7 @@
 | [display](display.md)                                     |  |
 | [docdir](docdir.md)                                       |  |
 | [docname](docname.md)                                     |  |
-| [editandcontinue](editAndContinue.md)                     |  |
+| [editandcontinue](editandcontinue.md)                     |  |
 | [editorintegration](editorintegration.md)                 | Enable or disable IDE integration |
 | [enablewarnings](enablewarnings.md)                       |  |
 | [endian](endian.md)                                       |  |

website/docs/Whats-New-in-5.0.md

@@ -63,7 +63,7 @@ title: What's New in 5.0
 * [dependson](dependson.md) (new)
 * [disablewarnings](disablewarnings.md) (new)
 * [dotnetframework](dotnetframework.md) (new)
-* [editandcontinue](editAndContinue.md) (new, replaces flag `NoEditAndContinue`)
+* [editandcontinue](editandcontinue.md) (new, replaces flag `NoEditAndContinue`)
 * [editorintegration](editorintegration.md) (new)
 * [enablewarnings](enablewarnings.md) (new)
 * [endian](endian.md) (new)
@@ -151,6 +151,6 @@ title: What's New in 5.0
 	* FloatFast, FloatStrict: use [floatingpoint](floatingpoint.md) instead
 	* Managed, Unsafe: use [clr](clr.md) instead
 	* NativeWChar: use [nativewchar](nativewchar.md) instead
-	* NoEditAndContinue: use [editandcontinue](editAndContinue.md) instead
+	* NoEditAndContinue: use [editandcontinue](editandcontinue.md) instead
 	* NoRTTI: use [rtti](rtti.md) instead.
 	* OptimizeSize, OptimizeSpeed: use [optimize](optimize.md) instead

website/docs/androidapilevel.md

@@ -0,0 +1,30 @@
+androidapilevel - This page was auto-generated. Feel free to help us improve the documentation by creating a pull request.
+
+```lua
+androidapilevel (value)
+```
+
+### Parameters ###
+
+`value` - needs documentation.
+
+## Applies To ###
+
+The `config` scope.
+
+### Availability ###
+
+Premake 5.0.0 alpha 14 or later.
+
+### Examples ###
+
+```lua
+androidapilevel (value)
+```
+
+<!-- This optional section should contain a list of links to any relevant pages.
+### See Also ###
+
+* [Another Page](anotherpage.md)
+-->
+

website/docs/androidapplibname.md

@@ -0,0 +1,30 @@
+androidapplibname - This page was auto-generated. Feel free to help us improve the documentation by creating a pull request.
+
+```lua
+androidapplibname (value)
+```
+
+### Parameters ###
+
+`value` - needs documentation.
+
+## Applies To ###
+
+The `config` scope.
+
+### Availability ###
+
+Premake 5.0.0 alpha 14 or later.
+
+### Examples ###
+
+```lua
+androidapplibname (value)
+```
+
+<!-- This optional section should contain a list of links to any relevant pages.
+### See Also ###
+
+* [Another Page](anotherpage.md)
+-->
+

website/docs/assemblydebug.md

@@ -0,0 +1,30 @@
+assemblydebug - This page was auto-generated. Feel free to help us improve the documentation by creating a pull request.
+
+```lua
+assemblydebug (value)
+```
+
+### Parameters ###
+
+`value` - needs documentation.
+
+## Applies To ###
+
+The `config` scope.
+
+### Availability ###
+
+Premake 5.0.0 alpha 16 or later.
+
+### Examples ###
+
+```lua
+assemblydebug (value)
+```
+
+<!-- This optional section should contain a list of links to any relevant pages.
+### See Also ###
+
+* [Another Page](anotherpage.md)
+-->
+

website/docs/boundscheck.md

@@ -0,0 +1,35 @@
+boundscheck - This page was auto-generated. Feel free to help us improve the documentation by creating a pull request.
+
+```lua
+boundscheck (value)
+```
+
+### Parameters ###
+
+`value` is one of:
+
+* `Default`: needs documentation
+* `Off`: needs documentation
+* `On`: needs documentation
+* `SafeOnly`: needs documentation
+
+## Applies To ###
+
+The `config` scope.
+
+### Availability ###
+
+Premake 5.0.0 alpha 14 or later.
+
+### Examples ###
+
+```lua
+boundscheck (value)
+```
+
+<!-- This optional section should contain a list of links to any relevant pages.
+### See Also ###
+
+* [Another Page](anotherpage.md)
+-->
+

website/docs/checkaction.md

@@ -0,0 +1,36 @@
+checkaction - This page was auto-generated. Feel free to help us improve the documentation by creating a pull request.
+
+```lua
+checkaction (value)
+```
+
+### Parameters ###
+
+`value` is one of:
+
+* `Default`: needs documentation
+* `D`: needs documentation
+* `C`: needs documentation
+* `Halt`: needs documentation
+* `Context`: needs documentation
+
+## Applies To ###
+
+The `config` scope.
+
+### Availability ###
+
+Premake 5.0.0 alpha 16 or later.
+
+### Examples ###
+
+```lua
+checkaction (value)
+```
+
+<!-- This optional section should contain a list of links to any relevant pages.
+### See Also ###
+
+* [Another Page](anotherpage.md)
+-->
+

website/docs/compilationmodel.md

@@ -0,0 +1,35 @@
+compilationmodel - This page was auto-generated. Feel free to help us improve the documentation by creating a pull request.
+
+```lua
+compilationmodel (value)
+```
+
+### Parameters ###
+
+`value` is one of:
+
+* `Default`: needs documentation
+* `File`: needs documentation
+* `Package`: needs documentation
+* `Project`: needs documentation
+
+## Applies To ###
+
+The `config` scope.
+
+### Availability ###
+
+Premake 5.0.0 alpha 14 or later.
+
+### Examples ###
+
+```lua
+compilationmodel (value)
+```
+
+<!-- This optional section should contain a list of links to any relevant pages.
+### See Also ###
+
+* [Another Page](anotherpage.md)
+-->
+