fix: updated docs styling

[lolrobbe2]

What does this PR do?
this pr aims to rectify #2551

format:

params non determenistic:

for params wich are not deterministic IE have standard values like architecture the following style is used:

`<param_name>` **param_type** - <description>.

params deterministic:

for params wich are deterministic a MD table is used:

for architecture:
arch is the enum/param name

| Arch           | Description                                      |
|-------------|--------------------------------------------------|
| universal    | Universal binaries supported by iOS and macOS    |
| x86            | 32-bit x86 architecture                          |
| x86_64       | 64-bit x86 architecture                          |
| ARM          | 32-bit ARM architecture                          |
| ARM64       | 64-bit ARM architecture                          |
| RISCV64     | 64-bit RISC-V architecture                       |

[Jarod42]

Both "value"/"arch" are wrong there (not valid value). value/arch would be good (variable might have a correct value)

[lolrobbe2]

the idea is to be able to extract the name and get the following:

function architecture(arch) end

[Jarod42]

It is the quotes that bore me (which shouldn't avoid the name extraction).

Some APIs accept mostly any strings, some quote are OKish, some expect specific string, and providing unexpected ones is confusing IMO.
architecture ("value") was already wrong, and should have been architecture (value) (or architecture ("%{value}")).
And then you should only have renamed 'value' to 'arch'.

[Jarod42]

Seems you use config in other places

[Jarod42]

'project' versus 'project config'?

[lolrobbe2]

@Jarod42 maby i should also add a file wich describes the docs styling.

and could you help me figure out a way to enforce this maby via CI?

[lolrobbe2]

@Jarod42 i started work on a js script that cheks the documentation format and logs potential errors and fails when errors are found.

i am also creating a helper script to streamline generating documentation files

[Jarod42]

if you have a script to check documentation, it should probably be called from https://github.com/premake/premake-core/blob/master/.github/workflows/website.yml to ensure consistency.
It just has to return non-zero in case of failure from CI point of view, but messages help humans :-)

[lolrobbe2]

if you have a script to check documentation, it should probably be called from https://github.com/premake/premake-core/blob/master/.github/workflows/website.yml to ensure consistency. It just has to return non-zero in case of failure from CI point of view, but messages help humans :-)

yes that is the goal, it is just a js script so can be run in the website task.

and logs precise errors when things are wrong

[KyrietS]

I'm against adding title and description front-matters when they are not necessary. If not set, the title of the page is its filename and it's fine for 99% of our pages. Same goes for description. Docusaurus takes first paragraph as a description so there is no need to repeat it in the front-matter. It's bug-prone and this PR proves it. This description is copied from another page :)

[KyrietS]

What is your algorithm for generating keywords for every page? Do they help you in any way? Because I am pretty much sure they will not affect searchability of our docs at all.