Add more docs (#121)

README.md

@@ -2,6 +2,7 @@
 
 [![build](https://github.com/chengcli/canoe/actions/workflows/main.yml/badge.svg)](https://github.com/chengcli/canoe/actions/workflows/main.yml)
 [![build](https://github.com/chengcli/canoe/actions/workflows/mac.yml/badge.svg)](https://github.com/chengcli/canoe/actions/workflows/mac.yml)
+[![DocStatus](https://readthedocs.org/projects/pycanoe/badge/?version=latest)](https://pycanoe.readthedocs.io/en/latest/?badge=latest)
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 [![codecov](https://codecov.io/gh/chengcli/canoe/branch/main/graph/badge.svg?token=hKnnv79a09)](https://codecov.io/gh/chengcli/canoe)
 

doc/README-custom-command.md

@@ -1,4 +1,6 @@
-# Writing custom git command
+## Writing custom git command
+
+This article introduces two extremely useful custom commands, `git send` and `git done`.
 
 Writing custom git commands are simple as these three steps:
     - Create a file with a name in the given format git-mycommand. And this file should be given executable access.
@@ -8,7 +10,7 @@ Writing custom git commands are simple as these three steps:
 Let’s write a custom git command to add, commit, and then push the changes to remote with one command.
 Let's call this command `git send`, which writes a useless commit message "wip".
 
-1. Creating a file for our command
+#### Step 1. Creating a file for our command
 It’s good to have a directory to contain all our custom commands. So that it will be organized. Let’s create a directory.
 
 ```
@@ -33,7 +35,7 @@ Last but not least, make that file as executable
 chmod +x git-send
 ```
 
-2. Add custom commands to $PATH
+#### Step 2. Add custom commands to $PATH
 
 This is quite important. This will help Git to recognize the custom commands.
 
@@ -50,10 +52,29 @@ You can now source the file or start a new instance of the terminal
 source ~/.zshrc
 ```
 
-3. Running our custom command
+#### Step 3. Running our custom command
 
 With everything in place, it’s time to run our custom command. Go to any of your local git repo and run the following command
 
 ```bash
 git send
 ```
+
+### The git-done command
+
+After your work has been merged into the main branch, you can safely delete
+your working branch and rebase your local main branch. These steps can be
+accomplished by the custom `git-done` command:
+
+```bash
+#!/bin/sh
+
+currentBranch=$(git symbolic-ref --short -q HEAD) # Getting the current branch
+
+git checkout main
+git fetch
+git rebase origin/main
+git branch -D $currentBranch
+```
+
+Both commands are provided in the ``.gitcustom`` folder in ``Canoe``.

doc/README-naming.md

@@ -19,13 +19,13 @@ suggest fixing your code according to the suggestions exactly. Your code won't b
 to merge into the main branch without passing the lints. Here are a few naming
 conventions to let you pass lints easier and help you write better and readable codes.
 
-### Name your folders and files
+### How to name folders and files
 - use a singular simple noun for folder names
 - avoid compound nouns for folder names
 - you can use compound nouns or phrases for files names
 - individual words in a compound nouns for phrase should be concatenated by underscore
 
-### Name your variables and classes
+### How to name variables and classes
 - use low case letters for variables
 - you can use compound nouns or phrases
 - compound nouns for phrase should be concatenated by underscore. This is called the *snake case*
@@ -34,7 +34,7 @@ conventions to let you pass lints easier and help you write better and readable
 - if a variable is a private member of a class, append the variable name with an
   underscore
 
-### Name your funcions
+### How to name funcions
 - functions names are usualy verbal phrases
 - standalone functions should use *snake case*
 - public class member functions should use *upper camel case*

doc/README-problems.md

@@ -1,14 +1,14 @@
 
-# Common problems
+## Troubleshooting
 
-## Cannot fetch RFM
-- Ask [email protected] for access to RFM (privately hosted)
+#### Trouble 1. Cannot fetch `RFM`
+- Ask [email protected] for access to `RFM` (privately hosted)
 - Give **full access** to your Github access token (classic)
 - Set environment variable `GH_ACCOUNT` to your Github username
 - Set environment variable `GH_TOKEN` to your Github access token (classic)
 - Source your `.bashrc` or `.zshrc` file
 
-## Cannot fetch RFM in Github actions
+#### Trouble 2. Cannot fetch `RFM` in Github actions
 - Set Github action secrets
     1. Go your repo -> `settings` -> `Secrets and variables` -> `Actions`.
     1. Set a `New repository secret` with name `ACCESS_TOKEN`.

doc/README-tips.md

@@ -1,5 +1,5 @@
 
-## Quick tips
+## Quick Git Tips
 - undo a "git add"
 ```
 git reset <file>

doc/README-workflow.md

@@ -1,21 +1,21 @@
-# How to use git for this repo 📌
+## How to use git for this repo 📌
 
 First and foremost, **stop using `git merge`**!
 
 When you search online, the recommended approach is to use `git merge` for merging changes. But this is wrong. It will lead to an unmaintainable codebase. In this repository, we adopt the idea of **linear history** and a **squash merging** approach , meaning there is only one permanent branch (`main`), and the only way to push changes to main is by submitting a Pull Request (PR).
 
 The `main` branch is protected to prevent direct pushes. **A linear history ensures that the main branch remains clean and organized**. Squash merging means that **the smallest unit of change is a PR, rather than a commit**.
 
-This workflow differs from some individual workflows where the smallest unit is usually a commit. For collaborative projects, commits can be too fine-grained and don't track issues effectively. Our aim is to ensure that each stage in the history solves a problem that can be traced back, providing context for that problem. In other words, development is **_issue-driven_**. The git workflow recommended for this repository goes as follows:
+This workflow differs from some individual workflows where the smallest unit is usually a commit. For collaborative projects, commits can be too fine-grained and don't track issues effectively. Our aim is to ensure that each stage in the history solves a problem that can be traced back, providing context for that problem. In other words, development is **issue-driven**. The git workflow recommended for this repository goes as follows:
 
-📍 Step 1. Submit an issue ticket on the GitHub website:
+#### Step 1. Submit an issue ticket on the GitHub website
 
 Before starting any work, create an issue ticket on GitHub to describe the problem or task you want to address.
 
 - If you plan to solve the issue yourself, a brief title without extensive details is sufficient.
 - If you want someone else to solve it, provide a more detailed explanation.
 
-📍 Step 2. Create a new branch locally
+#### Step 2. Create a new branch locally
 
 Once you have identified an issue or task, create a new branch locally using the following command:
 
@@ -25,11 +25,11 @@ git checkout -b <username/issue_description>
 
 The branch name should start with your username, followed by a slash `/` and then a brief description of the nature of the issue or task you're working on (for example, `cli/add_cpptest_case`). This naming convention helps keep the branch names consistent and makes it easier to identify the purpose of each branch, as well as who is working on it.
 
-📍 Step 3. Use the .gitignore file
+#### Step 3. Use the .gitignore file
 
 The `.gitignore` file helps keep your working directory clean. Each folder can have its own `.gitignore` file, which lists files that should not be tracked by the git system. For example, model output files should not be added to git. Ideally, when you run `git status`, there should be no untracked files in your working directory. This state is called a "clean workspace". When you sign off the work for today, please make sure that your workspace is clean. You do not need to worry about staging incomplete work. For your last commit of the day, use a meaningful description message because it is unsure when you will pick it up again.
 
-📍 Step 4. Add changed files to git
+#### Step 4. Add changed files to git
 
 If you put all untracked files in `.gitignore`, when you want to pause your work, you can simply use the following command to add your changes to git:
 
@@ -39,7 +39,7 @@ git add .
 
 This command adds all modified files to git (not yet commited), excluding the files listed in the `.gitignore` file.
 
-📍 Step 6. Commit your changes locally
+#### Step 5. Commit your changes locally
 
 After adding the changed files, use `git status` to review the modifications. If you accidentally added files that you don't want to include, you can undo the add by `git reset <file>`. Then, commit your changes locally with a message:
 
@@ -49,7 +49,7 @@ git commit -m "<message>"
 
 The content of the message is not crucial at this stage since all the commits within a PR will be squashed later into a single message that you'll write later. You can use a meaningful message like "work on XXX" or "working XXX," or a generic message like "wip" (work in progress).
 
-📍 Step 7. Upload your branch to GitHub
+#### Step 6. Upload your branch to GitHub
 
 The previous command only commits the changes locally. To push your changes to GitHub, use:
 
@@ -59,13 +59,13 @@ git push origin <username/issue_description>
 
 This command pushes your branch to the remote repository on GitHub. You should be able to see the remote branch by visiting the repository's page and looking for "insights/network."
 
-📍 Step 8. Submit a pull request (PR)
+#### Step 7. Submit a pull request (PR)
 
 This step is performed on the GitHub site. At this stage, only provide a title for the PR to indicate the purpose of the branch. No additional content is required.
 
 All subsequent commits and pushes to `<username/issue_description>` will be included in this PR. When the PR is merged into the `main` branch, all the commits in the PR will be squashed. At that point, you can write a meaningful title and description that document the changes, issues, usage, and any additional notes related to the PR.
 
-📍 Step 9. Update your local branch
+#### Step 8. Update your local branch
 
 After the PR merge, update your local branch by:
 

doc/index.rst

@@ -1,4 +1,16 @@
 User Guide of the Canoe Model
 =============================
 
-#.. doxygenindex::
+The following articles step sets the basics of properly using the ``Canoe`` repo.
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   Article 1: Workflow <README-workflow>
+   Article 2: git-send and git-done <README-custom-command>
+   Article 3: How to give names <README-naming>
+   Article 4: Git Tips <README-tips>
+   Article N: Troubleshooting <README-problems>