doc: Add Git Commit Guidelines

[yashi]

Introduce a simple guidelines for Git commits to ensure clear and effective communication in the development process. The guidelines cover:

• Ensuring code adheres to established coding standards.
• Avoiding the mixing of multiple logical changes in one commit.
• Prohibiting the introduction of new trailing white spaces.

[pr0me]

Looks good! I'd definitely suggest to reference the guidelines from the main README, e.g.,

## Contributing
Contributions are always welcome [...]

Please check out our [guidelines](doc/git-commit.md) before opening a Pull Request!

Also, maybe consider adding a link to one specific commit following the guidelines or include a full example in the docs. Having a concrete example at hand definitely helped me :)

[yashi]

@IlievIliya92 Would you mind helping me how to link to a .md from REDME.md?

• If I write [guidelines](doc/git-commit.md), it works when we read raw Markdown but it doesn't work on HTML
• If I write [guidelines](/git-commit.md), it doesn't work on raw Markdown but it works on HTML.

[yashi]

@pr0me Do you have any good one for our examples? I've picked a few but if you have one I'd love to add it.

[pr0me]

the examples you chose are perfect, thanks for adding them!

[IlievIliya92]

@IlievIliya92 Would you mind helping me how to link to a .md from REDME.md?

* If I write `[guidelines](doc/git-commit.md)`, it works when we read raw Markdown but it doesn't work on HTML

* If I write `[guidelines](/git-commit.md)`, it doesn't work on raw Markdown but it works on HTML.

Hi Yashi,

If the file itself git-commmit.md resides whitin the root directory of the doccumentation (doc) I think the correct syntax supported by both HTML and Md would be:

[guidelines](git-commit.md)

Sphinx will parse this line for HTML down to:

href="git-commit.html"

I hope this information was helpful to solve the issue.

[yashi]

Hi @IlievIliya92, Thanks. But the problem is

libcsp
├── README.md
└── doc
     └── git-commit.md

As you can see README.md and git-commit.md are in different dirs

[IlievIliya92]

Hi @IlievIliya92, Thanks. But the problem is

libcsp
├── README.md
└── doc
     └── git-commit.md

As you can see README.md and git-commit.md are in different dirs

Since the contents of the README.md file are directly included into the index.md file. I can suggest the following approach to solve this issue.

1. Add the link which is resolved properly for markdown.

README.md

[guidelines](./doc/git-commit.md) before opening a Pull Request!

2. Remove the include for the README.md, we are going to insert the contents of the file using a Sphinx source-read hook.

doc/index.md

-```{eval-rst}
-.. include:: ../README.md
-   :parser: myst_parser.sphinx_
-```

3. Insert the contents of the README file

Here we are using the sources-read Sphinx core event to preprocess the index file and insert the contents of the README.md file with the modified link in it.

doc/conf.py

def include_readme_file(app, docname, source):
    """
        This hook reads the contents of the README.md file, replaces the
        link for `git-commit` and inserts the modified contents in the index.md
        file before the first occuarance of  ```{toctree}
    """
    if docname == 'index':
        # Read and modify the contents of README
        with open("../../README.md", "r") as file:
            readme_contents = file.read()

        # Here we change the link for the `git-commit` page
        readme_contents = readme_contents.replace("./doc/git-commit.md", "git-commit")

        # Find the index of the first occurrence of ```{toctree}
        toctree_index = source[0].find('```{toctree}')
        if toctree_index != -1:
            # Insert the modified README files
            source[0] = source[0][:toctree_index] + readme_contents + source[0][toctree_index:]

def setup(app):
    app.connect('source-read', include_readme_file)

This approach would allows us to use markdown syntax from the README.md file and modify them before procesing the HTML docs.

Here is a patch with all the changes for the solution propoused above.

From d9173ddb1bdb850b19272bf5dfa7ba469ade04f5 Mon Sep 17 00:00:00 2001
From: Iliya Iliev <[email protected]>
Date: Mon, 4 Mar 2024 12:53:36 +0200
Subject: [PATCH] doc: Add suport for .md and HTML links for README.md file

Signed-off-by: Iliya Iliev <[email protected]>
---
 README.md    |  2 +-
 doc/conf.py  | 23 +++++++++++++++++++++++
 doc/index.md |  4 ----
 3 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index c30e8d2..d2df55a 100644
--- a/README.md
+++ b/README.md
@@ -69,7 +69,7 @@ The latest version of the /doc folder is compiled to HTML and hosted on:
 Thank you for considering contributing to libcsp! We welcome
 contributions from the community to help improve and grow the
 project. Please take a moment to review our
-[guidelines](/git-commit.md) before opening a Pull Request!
+[guidelines](./doc/git-commit.md) before opening a Pull Request!
 
 ## Software license
 
diff --git a/doc/conf.py b/doc/conf.py
index d8b7f0b..e24f284 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -69,6 +69,29 @@ html_theme_options = {
     'sticky_navigation': True
 }
 
+def include_readme_file(app, docname, source):
+    """
+        This hook reads the contents of the README.md file, replaces the
+        link for `git-commit` and inserts the modified contents in the index.md
+        file before the first occuarance of  ```{toctree}
+    """
+    if docname == 'index':
+        # Read and modify the contents of README
+        with open("../../README.md", "r") as file:
+            readme_contents = file.read()
+
+        # Here we change the link for the `git-commit` page
+        readme_contents = readme_contents.replace("./doc/git-commit.md", "git-commit")
+
+        # Find the index of the first occurrence of ```{toctree}
+        toctree_index = source[0].find('```{toctree}')
+        if toctree_index != -1:
+            # Insert the modified README files
+            source[0] = source[0][:toctree_index] + readme_contents + source[0][toctree_index:]
+
+def setup(app):
+    app.connect('source-read', include_readme_file)
+
 version = pygit2.Repository('.').head.shorthand
 
 # Add any paths that contain custom static files (such as style sheets) here,
diff --git a/doc/index.md b/doc/index.md
index a0194a4..9272206 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -6,10 +6,6 @@ Disclaimer: You are reading the latest version of libcsp document from
 [the `develop` branch](https://github.com/libcsp/libcsp).  Currently,
 we only have this version in HTML format.
 
-```{eval-rst}
-.. include:: ../README.md
-   :parser: myst_parser.sphinx_
-```
 
 ```{toctree}
 :caption: Setup
-- 
2.34.1

[yashi]

@IlievIliya92, super thanks! It works like a charm. I've appended your commit on top of mine.

[yashi]

And now with a commit message

[yashi]

This PR now depends on #538.