diff --git a/.editorconfig b/.editorconfig index b74379b..0eae508 100644 --- a/.editorconfig +++ b/.editorconfig @@ -17,3 +17,17 @@ curly_bracket_next_line = true # Preserve whitespace for Markdown [*.md] trim_trailing_whitespace = false + +# YAML indentation +[*.yaml] +indent_size = 2 +tab_width = 2 + +[*.yml] +indent_size = 2 +tab_width = 2 + +# TOML indentation +[*.toml] +indent_size = 2 +tab_width = 2 diff --git a/.github/workflows/markdown-lint.yml b/.github/workflows/markdown-lint.yml new file mode 100644 index 0000000..c0f8a00 --- /dev/null +++ b/.github/workflows/markdown-lint.yml @@ -0,0 +1,29 @@ +name: Markdown Lint + +on: + pull_request: + types: [opened, synchronize, reopened] + branches: ["main"] + +permissions: + contents: read + statuses: write + +jobs: + md-lint: + name: Markdown Lint + runs-on: ubuntu-latest + + steps: + - name: Checkout Code + uses: actions/checkout@v5 + with: + fetch-depth: 0 + persist-credentials: true + + - name: MarkdownLint + uses: DavidAnson/markdownlint-cli2-action@v20 + with: + globs: | + docs/**/*.md + README.md diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000..2271a19 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,39 @@ +# markdownlint configuration +# See: https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml + +# Default state for all rules +default: true + +# Ignore all files/folders ignored by git +gitignore: true + +# Use dashes for list items +MD004: + style: dash + +# Unordered list indentation +MD007: + indent: 4 + +# Disable line length rules +MD013: false + +# Allow inline HTML +MD033: false + +# Allow multiple headings with the same content +MD024: + siblings_only: true + +# Allow preamble text before the primary heading +MD041: + allow_preamble: true + +# Natural list ordering +MD029: false + +# Allow headings to end with punctuation +MD026: false + +# Allow different block styles per file +MD046: false diff --git a/README.md b/README.md index c1e80c6..9dc741d 100644 --- a/README.md +++ b/README.md @@ -20,4 +20,4 @@ You are free to: For the full legal text, see [LICENSE](LICENSE) or visit [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/). ---- \ No newline at end of file +--- diff --git a/docs/index.md b/docs/index.md index 90917a1..fd4bf2b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -# Homepage +# Homepage For full documentation visit [mkdocs.org](https://www.mkdocs.org). @@ -12,7 +12,7 @@ Some `code` goes here. A plain codeblock: -``` +``` py Some code here def myfunction() // some comment @@ -59,7 +59,7 @@ def bubble_sort(items): ## Icons and Emojs -:smile: +:smile: :fontawesome-regular-face-laugh-wink: diff --git a/docs/philosophy.md b/docs/philosophy.md index 14a54d6..e977c60 100644 --- a/docs/philosophy.md +++ b/docs/philosophy.md @@ -27,7 +27,7 @@ This section outlines the core principles guiding how we design, implement, and Use assertions, debug-only checks and logging generously where appropriate. !!! success "Prioritize runtime performance" - Every design choice should consider its impact on real-time execution. + Every design choice should consider its impact on real-time execution. Performance is not an afterthought — it's a primary goal, especially in hot code-paths. !!! success "Optimize, optimize, optimize" diff --git a/docs/project/ide-requirements.md b/docs/project/ide-requirements.md index d3e0398..ed59e28 100644 --- a/docs/project/ide-requirements.md +++ b/docs/project/ide-requirements.md @@ -5,6 +5,7 @@ This section specifies the *Integrated Development Environment* (IDE) requiremen --- ## IDE + Intricate development requires **Microsoft Visual Studio 2022 or newer**. A secondary text editor may also be used with **Visual Studio**, but should **not replace it**. Suggested secondary text editors are: - VS Code diff --git a/docs/project/setup.md b/docs/project/setup.md index 061a8a7..360d395 100644 --- a/docs/project/setup.md +++ b/docs/project/setup.md @@ -7,6 +7,7 @@ This section outlines how to setup Intricate after cloning the repository. ## Cloning Intricate must be **recursively cloned** to properly pull all the required submodules. Recursive cloning may be done either via the **GitHub Desktop** application, or with the following command: + ``` shell git clone --recurse-submodules https://github.com/DnA-IntRicate/IntricateEngine ``` @@ -20,25 +21,26 @@ Intricate uses [Premake5](https://premake.github.io/) as its build system. The p !!! example "Example Premake file" ``` lua workspace "IntricateEngine" - configurations { "Debug", "Release" } + configurations { "Debug", "Release" } project "IntricateEditor" - kind "ConsoleApp" - language "C++" - files { "**.hpp", "**.cpp" } + kind "ConsoleApp" + language "C++" + files { "**.hpp", "**.cpp" } - filter "configurations:Debug" - defines { "_IE_DEBUG" } - symbols "On" + filter "configurations:Debug" + defines { "_IE_DEBUG" } + symbols "On" - filter "configurations:Release" - defines { "_IE_RELEASE" } - optimize "On" + filter "configurations:Release" + defines { "_IE_RELEASE" } + optimize "On" ``` --- ## How To Setup + - Run the setup script `Setup.py`, which will validate and or install the required versions of **Python**, **.NET** and the **Vulkan SDK**. - You may have to run the script multiple times and or restart your computer as prompted by the script for all the **required environment variables** to be properly registered. - Once all this is done, the script will call the `GenerateVS.py` script which then uses Premake to generate all projects files targetting **Visual Studio 2022**. diff --git a/docs/style/comments.md b/docs/style/comments.md index b7514f7..9fef4b8 100644 --- a/docs/style/comments.md +++ b/docs/style/comments.md @@ -6,7 +6,7 @@ This section outlines the conventions used for writing comments in code. ## Comment Structure -**General format of a comment:** +**General format of a comment:** ``` C++ // ([optional metadata]): @@ -22,6 +22,7 @@ This section outlines the conventions used for writing comments in code. When including metadata, list multiple elements as **comma-separated values** without spaces. Example: + ``` C++ // FIXME(Adam,medium): These allocations are leaking memory and need to be fixed! ``` diff --git a/docs/style/cpp-style.md b/docs/style/cpp-style.md index c3c924f..7fdfd61 100644 --- a/docs/style/cpp-style.md +++ b/docs/style/cpp-style.md @@ -39,11 +39,11 @@ Intricate uses [.editorconfig](https://editorconfig.org/) to enforce code-stylin - Do not leave trailing whitespace.\* - Use **exactly one space** after commas and semicolons inside parameter lists and other constructs.\* - Use **exactly one space** before and after binary operators.\* - - Example: `a + b`, `x == 3`, `value * 2` - - **No spaces** for: - - Indexing: `arr[i]` - - Unary operators: `-x`, `!flag`, `~mask`, `++i`, `i--` - - Scope resolution: `std::string` + - Example: `a + b`, `x == 3`, `value * 2` + - **No spaces** for: + - Indexing: `arr[i]` + - Unary operators: `-x`, `!flag`, `~mask`, `++i`, `i--` + - Scope resolution: `std::string` - Insert a **final newline** at the end of source files.\* !!! warning @@ -52,17 +52,19 @@ Intricate uses [.editorconfig](https://editorconfig.org/) to enforce code-stylin ### Braces - Use the **Allman style**\*: + ``` C++ void Foo() { if (true) { - // Block-bodies covering multiple lines must always have the opening brace on a newline. + // Block-bodies covering multiple lines must always have the opening brace on a newline. } } ``` - Omit the braces for single-line control-flow blocks: + ``` C++ if (true) Foo(); @@ -77,21 +79,24 @@ if (printNumbers) ``` - Empty function bodies should be defined as: + ``` C++ void Foo() { }; // Inlined empty braces with a space in-between ended with a semicolon ``` - Multi-line lambda function bodies should have their braces indented\*: + ``` C++ Helpers::FetchExecuteIfValid(nativeID, [&](const Ref& scene) - { - scene->DestroyEntity(entityID); - }); +{ + scene->DestroyEntity(entityID); +}); ``` ### Control Flow Blocks - Do not inline control-flow blocks: + ``` C++ // Don't do this while (true) DoWork(); @@ -107,6 +112,7 @@ while (true) ### Pointers and References - Place `*` and `&` adjacent to the type\*: + ``` C++ int* ptr; const Foo& ref; @@ -117,6 +123,7 @@ const Foo& ref; ### Preprocessor Directives - Preprocessor directives should be indented and follow an independent indentation level: + ``` C++ #ifdef _IE_ENABLE_LOGGING # define _IE_NATIVE_USE_TYPE_TRACKING diff --git a/docs/style/csharp-style.md b/docs/style/csharp-style.md index 8a4f3bb..951c861 100644 --- a/docs/style/csharp-style.md +++ b/docs/style/csharp-style.md @@ -39,10 +39,10 @@ Intricate uses [.editorconfig](https://editorconfig.org/) to enforce code-stylin - Do not leave trailing whitespace.\* - Use **exactly one space** after commas and semicolons inside parameter lists and other constructs.\* - Use **exactly one space** before and after binary operators.\* - - Example: `a + b`, `x == 3`, `value * 2` - - **No spaces** for: - - Indexing: `arr[i]` - - Unary operators: `-x`, `!flag`, `~mask`, `++i`, `i--` + - Example: `a + b`, `x == 3`, `value * 2` + - **No spaces** for: + - Indexing: `arr[i]` + - Unary operators: `-x`, `!flag`, `~mask`, `++i`, `i--` - Insert a **final newline** at the end of source files.\* !!! warning @@ -51,6 +51,7 @@ Intricate uses [.editorconfig](https://editorconfig.org/) to enforce code-stylin ### Braces - Use the **Allman style**\*: + ``` C# public void Foo() { @@ -62,6 +63,7 @@ public void Foo() ``` - Omit the braces for single-line control-flow blocks: + ``` C# if (true) Foo(); @@ -76,6 +78,7 @@ if (printNumbers) ``` - Empty function bodies should be defined as: + ``` C# public void Foo() { } // Inlined empty braces with a space in-between ``` @@ -83,6 +86,7 @@ public void Foo() { } // Inlined empty braces with a space in-between ### Control Flow Blocks - Do not inline control-flow blocks: + ``` C# // Don't do this while (true) DoWork(); @@ -162,6 +166,7 @@ See: [Comments](comments.md). ### Modifier Order Field modifiers should appear in the following order: + ``` C# // This ordering is enforced by .editorconfig and can be auto-applied from Visual Studio hints public, private, protected, internal, static, extern, new, virtual, abstract, sealed, partial, override, readonly, unsafe, volatile, async @@ -170,6 +175,7 @@ public, private, protected, internal, static, extern, new, virtual, abstract, se ### Expression Syntax - Use expression-bodied members for trivial property getters and simple inline methods: + ``` C# public int Count => m_Count; @@ -180,6 +186,7 @@ public float Mass } public bool Awake() => Bindings.RigidBody_Awake(m_NativeID); + ``` - Use block-bodies for everything else. @@ -187,6 +194,7 @@ public bool Awake() => Bindings.RigidBody_Awake(m_NativeID); ### Pattern Matching - Favor pattern matching over explicit type casting when checking types. + ``` C# public class Entity { @@ -223,6 +231,7 @@ public class Entity - Minimize the `unsafe` scope as far as possible. - Avoid declaring methods and types as `unsafe`. + ``` C# // Avoid declaring the method as unsafe public void CopyToNative(ReadOnlySpan data, nint dst) diff --git a/docs/style/naming-conventions.md b/docs/style/naming-conventions.md index 19dd818..e74ca06 100644 --- a/docs/style/naming-conventions.md +++ b/docs/style/naming-conventions.md @@ -70,7 +70,7 @@ Boolean function and variable names should indicate a condition or state. ## Function/Method Naming -- Functions should be **action-oriented** and effectively describe their behavior using *verbs* - even if it means that the function name may become longer. +- Functions should be **action-oriented** and effectively describe their behavior using *verbs* - even if it means that the function name may become longer. - Avoid unreadable abbreviations! | Action Category | Prefix Examples | Function Examples | @@ -129,7 +129,7 @@ Boolean function and variable names should indicate a condition or state. ## File Naming Rules -- File names should reflect the primary type or purpose. +- File names should reflect the primary type or purpose. - Use one main class or responsibility per file where practical. !!! example @@ -139,11 +139,11 @@ Boolean function and variable names should indicate a condition or state. ## Folder Naming Rules -- Folders are created for every major or minor subsystem that requires the implementation of multiple source files. +- Folders are created for every major or minor subsystem that requires the implementation of multiple source files. !!! example There are many source files part of the `Math` library, therefore these files are deserving of their own folder: `IntricateEngine/Math/` -- Folders should always be named in **PascalCase** except in instances where a certain directory tree is required to follow a different convention for a particular toolchain; such as using **kebab-case** folder names for web-based toolchains. +- Folders should always be named in **PascalCase** except in instances where a certain directory tree is required to follow a different convention for a particular toolchain; such as using **kebab-case** folder names for web-based toolchains. ---