diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..e967f24 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,27 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'light' +copyright = '2025, light7734' +author = 'light7734' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] diff --git a/docs/guidelines/conventions.rst b/docs/guidelines/conventions.rst index 45117e1..d49f737 100644 --- a/docs/guidelines/conventions.rst +++ b/docs/guidelines/conventions.rst @@ -1,7 +1,10 @@ +.. guidelines/conventions + 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 follow these guidelines. + +AAA +-------------------- diff --git a/docs/guidelines/development.rst b/docs/guidelines/development.rst new file mode 100644 index 0000000..ba4baa0 --- /dev/null +++ b/docs/guidelines/development.rst @@ -0,0 +1,95 @@ +.. guidelines/development + +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. + +Such a plan should: + +- Define a way to **distribute work** (across time, since there's only 1 developer). +- Define what is a **unit of work** (cycles). +- Provide a way to **track productivity**, which helps projecting the future and **detecting patterns** early on. +- Provide a **pipeline** for the work to go through and **minimize ambiguity**. + +These are the **management** aspects of the project, which help the development goals to be more **pragmatic** +---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 + - Write the commit message. + - This limits the **scope of changes** and gives you a very specific **goal** to work towards. + - If something outside of this scope really bothers you, fix and stash for a future cycle. + - Make a ticket if stash-fix is implausible ---**DO NOT** write **todo** comments. + - The message should follow the project's **commit message specifications**. + + - Make a ticket. + - Version control (git) is a **development-tool**, not a **management-tool**. + - Provide a very brief description ---This may be used in the commit message's body. + +2 - Make it work + - Write high-level tests that confirms the cycle's requirements are met. + - That is, specify requirements in a programming language instead of English. + - You're done when all the tests pass. + - Preferably write the tests first, but it's okay to start with the interface. + - Tests may not be necessary depending on the requirements and commit type. + + - "Make it work" doesn't mean liberally producing shit code, you should: + - Follow project's **conventions**. + - Follow **best practices** and **proven swe principles**. + - Enable **warnings as errors**. + - Enable **static analysis**. + - Don't break any pre-existing-tests. + - Have the over-all picture in mind. + +3 - Make it right + - Test driven refactoring + - Now you have a better picture of how things relate and work. + - Switch to a TDD-style development to do the refactoring while following swe best-practices and proven-principles. + +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. + + +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 `_. + +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. + +- fix + - For fixing an issue. + - Coressponds to a **patch** semantic bump in version. + +- build + - For changes to the build pipeline. + - Coressponds to a **patch** semantic bump in 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. + - Does not affect the version. + +- asset +- test diff --git a/docs/index.rst b/docs/index.rst index 3dea870..f792088 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,20 @@ -A bleeding-edge, cross-platform, cross-graphics-api, minimal-dependencies modern game-engine. +.. 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 `_ +documentation for details. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + guidelines/development.rst + guidelines/conventions.rst -Supported Platforms: Windows, Mac, Linux, FreeBSD -Supported GraphicsAPIs: DirectX12-Ultimate, Vulkan 1.4, Metal, OpenGL 4.6 -Dependencies: stdlib, meshoptimizer diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd