docs(guidelines/conventions): minor changes

for generating changelogs :D

docs/.gitignore

@@ -0,0 +1,3 @@
+_build/
+generated/
+

docs/architecture/assets.rst

@@ -1,62 +1,72 @@
 Asset Management
 ===================================================================================================
-Layout
+
+On Disk (file) Layout
 ---------------------------------------------------------------------------------------------------
-{version}              | 4 bytes, ie. uint32_t
-{general metadata}     | sizeof(AssetMetadata)
-{specialized metadata} | sizeof(XXXAssetMetadata), eg. TextureAssetMetadata
-{n}                    | 4 bytes, ie. uint32_t
-{blob_0...n metadata}  | n * sizeof(BlobMetadata)
-{blob_0...n data}      | variable size based on actual data
-{end marker}           | 8 byte, ie size_t for marking the END
+
+.. code-block:: md
+
+    {version}              | 4 bytes, ie. uint32_t
+    {general metadata}     | sizeof(AssetMetadata)
+    {specialized metadata} | sizeof(XXXAssetMetadata), eg. TextureAssetMetadata
+    {n}                    | 4 bytes, ie. uint32_t
+    {blob_0...n metadata}  | n * sizeof(BlobMetadata)
+    {blob_0...n data}      | variable size based on actual data
+    {end marker}           | 8 byte, ie size_t for marking the END
 
 Sections
 ---------------------------------------------------------------------------------------------------
-version              -> The version of the asset for forward compatibility
-general metadata     -> Common asset metadata such as file-path, asset-type, creator, etc.
-specialized metadata -> Metadata specific to the asset, eg. texture dimensions for Textures.
-n                    -> The number of blobs.
-blob_0...n metadata  -> Metadata specifying how the actual data is packed, required for unpacking.
-blob_0...n data      -> The actual data, packed and compressed to be reacdy for direct engine consumption.
+
+.. code-block:: md
+
+    version              -> The version of the asset for forward compatibility
+    general metadata     -> Common asset metadata such as file-path, asset-type, creator, etc.
+    specialized metadata -> Metadata specific to the asset, eg. texture dimensions for Textures.
+    n                    -> The number of blobs.
+    blob_0...n metadata  -> Metadata specifying how the actual data is packed, required for unpacking.
+    blob_0...n data      -> The actual data, packed and compressed to be reacdy for direct engine consumption.
 
 Loading
 ---------------------------------------------------------------------------------------------------
-Each `Loader` has ONE OR MORE supported input file types (detected via the file extension): eg. StbLoader -> Can read in .jpg, .png, .bmp, etc.... files
+Loading pre-baked asset files (like .png files) for baking:
 
-Each `Loader` has ONLY ONE supported output asset type:
+
+Each **Loader** has ONE OR MORE supported input file types (detected via the file extension): eg. StbLoader -> Can read in .jpg, .png, .bmp, etc.... files
+
+Each **Loader** has ONLY ONE supported output asset type:
 eg. StbLoader -> outputs TextureAsset
 
-Multiple `Loader`s MAY have as output the same asset type:
+Multiple **Loader**\s MAY have as output the same asset type:
 eg. StbLoader -> outputs TextureAsset
 eg. SomeOtherImgLoader -> outputs TextureAsset
 
-Multiple `Loader`s SHOULD NOT have as input same extension types
-eg. .jpg, .png -> if supported, should only be supported by 1 `Loader` class
+Multiple **Loader**\s SHOULD NOT have as input same extension types
+eg. .jpg, .png -> if supported, should only be supported by 1 **Loader** class
 
-Each `Loader` SHOULD read and turn the data from a file (eg. .png for textures) into something
-understandable by a `Packer` (not the engine itself).
+Each **Loader** SHOULD read and turn the data from a file (eg. .png for textures) into something
+understandable by a **Packer** (not the engine itself).
 
-A `Loader` SHOULD NOT be responsible for packing the parsed file data into asset data,
+A **Loader** SHOULD NOT be responsible for packing the parsed file data into asset data,
 as that implies direct understanding of the layout required by the engine. 
 
-And if that layout changes, ALL `Loader`s should change accordingly; 
+And if that layout changes, ALL **Loader**s should change accordingly; 
 which makes a class that's responsible for reading files dependant on the engine's (potentially frequent) internal changes.
-The logic is to reduce many-to-one dependency into a one-to-one dependency by redirecting the packing process to `Packer` classes
+The logic is to reduce many-to-one dependency into a one-to-one dependency by redirecting the packing process to **Packer** classes
 
 Packing
 ---------------------------------------------------------------------------------------------------
-Each `Packer` is responsible for packing ONLY ONE asset type:
+Each **Packer** is responsible for packing ONLY ONE asset type:
 eg. TexturePacker for packing texture assets from parsed image files.
 eg. ModelPacker for packing model assets from parsed model files.
 
-Each `Packer` will output ONE OR MORE blobs of data, 
+Each **Packer** will output ONE OR MORE blobs of data, 
 and for EACH blob of data, it'll write a BlobMetadata, AFTER the specialized metadata (eg. TextureAssetMetadata)
 
-A `Packer` will make use of the `Compressor` classes to compress the data,
+A **Packer** will make use of the **Compressor** classes to compress the data,
 and lay it out in a way that is suitable for the engine's consumption.
 
 Unpacking
 ---------------------------------------------------------------------------------------------------
-A `Parser` is responsible for parsing ONLY ONE asset type:
+A **Parser** is responsible for parsing ONLY ONE asset type:
 eg. TextureParser for parsing texture assets for direct engine consumption.
 eg. ModelParser  for parsing model assets for direct engine consumption.

docs/architecture/resource.rst

@@ -1,4 +1,5 @@
-Resource Management
+.. architecture/resources
 
+Resource Management
 ===================================================================================================
 

docs/generate_changelog.py

@@ -0,0 +1,68 @@
+from git import Repo
+import re
+
+repo = Repo(search_parent_directories=True)
+assert not repo.bare
+
+file_path = "generated/changelog.rst"
+
+messages = []
+short_shas = []
+hex_shas = []
+logs = []
+
+remote_url = "https://git.light7734.com/light7734/light/commit"
+def format_log(commit_type, message, major, minor, patch, short_sha, hex_sha):
+    href = f"{remote_url}/{hex_sha}"
+    version = f"{major}.{minor}.{patch}-kitten+{short_sha}";
+    link = f"`{version} <{remote_url}/{hex_sha}>`__"
+    return f"| **{message}** ({link})"
+
+for commit in repo.iter_commits():
+    messages.append(commit.summary)
+    short_shas.append(repo.git.rev_parse(commit.hexsha, short=5))
+    hex_shas.append(commit.hexsha)
+
+ver_major = 0
+ver_minor = 0
+ver_patch = 0
+
+idx = len(messages)
+for message in reversed(messages):
+    idx = idx - 1;
+
+    commit_type = re.match("^(feat|fix|refactor|perf|build|asset|test|chore|ci|docs)", message)
+    if not commit_type:
+        continue
+
+    match commit_type.group(0):
+        case "feat":
+            ver_minor = ver_minor + 1
+            ver_patch = 0
+
+        case "fix":
+            ver_patch = ver_patch + 1
+
+        case "refactor":
+            ver_patch = ver_patch + 1
+
+        case "perf":
+            ver_patch = ver_patch + 1
+
+        case "build":
+            ver_patch = ver_patch + 1
+
+        case "asset":
+            ver_patch = ver_patch + 1
+
+    logs.append(format_log(commit_type, message, ver_major, ver_minor, ver_patch, short_shas[idx], hex_shas[idx]))
+
+with open(file_path, "w") as f:
+    f.write(".. changelogs\n\n\n")
+    f.write("Changelogs\n")
+    f.write("==================================================\n\n")
+
+    f.write("KITTEN\n")
+    f.write("--------------------------------------------------\n\n")
+    for log in reversed(logs):
+          f.write(log + '\n')

docs/guidelines/conventions.rst

@@ -3,7 +3,7 @@
 Coding Conventions
 ===================================================================================================
 Any line of code added to the engine, must abide by following conventions.
-They may seem arbitrary, and sometimes they are, but to be consistent (which is not an arbitrary goal) is to
+They may seem arbitrary, and sometimes they are. But to achieve **consistency**, which is not an arbitrary goal, is to
 follow these guidelines.
 
 AAA

docs/guidelines/development.rst

@@ -2,8 +2,8 @@
 
 Development
 ===================================================================================================
-As a solo-project, I am not only the **developer**, but also the **manager** of this project. Therefore
-there is a need, if this project is to succeed, to have a development plan. 
+As a solo-project, I am not only the **developer**, but also the **manager**. 
+Therefore there is a need, if this project is to succeed, to have a development plan. 
 
 Such a plan should:
 
@@ -16,7 +16,7 @@ These are the **management** aspects of the project, which help the development
 ---by pulling my mind out of its **engineering dreamland**, and make it focus on the **broader picture**.
 
 Cycle
---------------------
+---------------------------------------------------------------------------------------------------
 A cycle is one **step** in development, one cycle = one ticket, and it consists of 4 stages:
 
 1 - Make it known
@@ -53,43 +53,95 @@ A cycle is one **step** in development, one cycle = one ticket, and it consists
 4 - Make it fast
     - This is an engine, at the end of the day, **performance** is king.
     - Get a performance and/or memory profile and try to alleviate the bottlenecks.
+    - Avoid premature optimizations, be certain what you change has performance benefits.
 
 
 Sprint
---------------------
+---------------------------------------------------------------------------------------------------
 A sprint is the collection of all the finished cycles in one week.
 It's meant to provide insight on development speed and help projecting the future.
 
 
 Commit Message Specification
---------------------
+---------------------------------------------------------------------------------------------------
 The project follows the `Conventional Commits Specification <https://www.conventionalcommits.org/en/v1.0.0-beta.4>`_.
 
+.. code-block:: md
+
+    <type>[optional scope]: <description>
+
+    [optional body]
+
+    [optional footer]
+
 With the following commit types:
 
 - feat
-    - For adding new features.
-    - Coressponds to a **minor** semantic bump in version.
-
-- refactor
-    - For refactoring existing code.
-    - Coressponds to a **patch** semantic bump in version.
+    - For adding a new feature.
+    - Causes a **minor** bump in version.
 
 - fix
-    - For fixing an issue.
-    - Coressponds to a **patch** semantic bump in version.
+    - For changes that fix one or more bug.
+    - Causes a **patch** bump in version.
+
+- refactor
+    - For non feat/fix changes that improve the implementation and/or the interface.
+    - Causes a **patch** bump in version.
+
+- perf
+    - For changes that (hopefully) improve the performance.
+    - Causes a **patch** bump in version.
 
 - build
-    - For changes to the build pipeline.
-    - Coressponds to a **patch** semantic bump in version.
+    - For changes that affect the build system or external dependencies.
+    - Causes a **patch** bump in version.
+
+- asset
+    - For changes to the files under the ``/data`` directory.
+    - Causes a **patch** bump in version.
+
+- test
+    - For adding missing tests or correcting the existing tests.
+    - Does not affect the version.
 
 - chore
     - For releases, .gitignore changes, deleting unused files, etc.
     - Does not affect the version.
 
 - ci
-    - For anything related to the ci/cd pipelines like .drone.yml changes.
+    - For changes to our CI configuration files and scripts, including files under ``/tools/ci``.
     - Does not affect the version.
 
-- asset
-- test
+- docs
+    - For changes to the documentations.
+    - Does not affect the version.
+
+Semantic Versioning
+---------------------------------------------------------------------------------------------------
+Coupled with conventional commit style messages, we can automajically version the project following
+the **Semantic Versioning 2.0.0** specifications.
+
+The full version identifier consits of a version core (major.minor.patch) + label + hexsha of the commit.
+Using the following format:
+
+
+.. code-block:: md
+
+    <major>.<minor>.<patch>-<label>+<short_hexsha>
+
+    eg.
+    0.8.1-kitten+ea898 
+    0.5.0-kitten+01d85
+    1.5.0-akasha+7de53
+
+    kitten refers to all pre-release (1.0.0) versions
+
+
+The shortened hexsha of a commit is obtained by:
+``git rev-parse --short=5 <commit_hexsha>``
+
+
+
+
+
+

docs/guidelines/philosophy.rst

@@ -0,0 +1,7 @@
+.. guidelines/philosophy
+
+Philosophy
+===================================================================================================
+
+| **A theory or attitude that acts as a guiding principle for behaviour.**
+| --- Oxford Languages

docs/index.rst

@@ -1,20 +1,32 @@
-.. light documentation master file, created by
-   sphinx-quickstart on Tue Aug  5 12:20:54 2025.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-light documentation
-===================
-
-Add your content using ``reStructuredText`` syntax. See the
-`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-documentation for details.
+.. light documentation
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Light Engine
 
+   light/showcase.rst
+   light/features.rst
+   
+.. toctree::
+   :maxdepth: 2
+   :caption: Software Architecture
+
+   architecture/assets.rst
+   architecture/resource.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Development Guidelines
+
+   guidelines/philosophy.rst
    guidelines/development.rst
    guidelines/conventions.rst
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Generated Docs
+
+   generated/api.rst
+   generated/changelog.rst
+
 

docs/light/features.rst

@@ -0,0 +1,4 @@
+.. light/features
+
+Features
+===================================================================================================

docs/light/showcase.rst

@@ -0,0 +1,4 @@
+.. light/demos
+
+Showcase
+===================================================================================================