diff --git a/docs/source/For Developer/A Completed Pull Request.md b/docs/source/For Developer/A Completed Pull Request.md index 565baeae..38510945 100644 --- a/docs/source/For Developer/A Completed Pull Request.md +++ b/docs/source/For Developer/A Completed Pull Request.md @@ -13,10 +13,12 @@ Takeaway: image -3. Use `git clone ` to clone the remote codebase into your local machine through the command line. No worry if your shell (command line) looks different from mine (The operations are same in the Mac and Windows systems). +3. Use `git clone ` to clone the remote codebase into your local machine through the command line. No worry if your shell (command line) looks different from mine (The operations are same in the Mac and Windows systems. Note that the operations are same in both CMD and Powershell so we only show the CMD). image + image + 4. Switch into **geochemistrypi** repository. Activate your virtual environment (**venv** or **conda**). In this case, I use conda to set up. It is a good habit to use a specific virtual environment for a specific Python project. Then, use `pip install -r requirements.txt` to download the dependencies. image @@ -27,7 +29,7 @@ Takeaway: image - image + image 6. Use **Visual Studio Code** (Recommended IDE) to open the codebase and don't forget to activate your virtual environment as the picture shows below. @@ -37,7 +39,7 @@ Takeaway: image - image + image 8. Do some modifications on the codebase. For example, in this case, I update the badge information of READM.md. @@ -47,16 +49,22 @@ Takeaway: image + image + 10. It is a good habit to use `git diff ` check whether the changed content on that specific files respectively is what you desire to make. After enter the command, the console will switch into **diff display**. In **diff displays** , press the keybord `j` to scroll down and press the keyboard `k` to scroll up. `+` refers to the line added while `-` refers to the line deleted. Press the keyboard `q` to exit from the **diff display** after checking. image - image + image + + image 11. Use `git add ` to staged the files for commit. image + image + 12. Use `git commit -m "tag: message"` to make a local commit. It is a good habit to follow up the principle that one commit for one functionality implementation or one optimization or one bug fix. It is allowed to push multiple commits to the remote codebase with one pull request. Please include the following tags in the beginning of your commit message to make more organized commits and PRs. It would tell exactly what use it is in this commit. @@ -76,6 +84,8 @@ Takeaway: image + image + 13. Continuous Integration (CI): In our codebase, we set up a pre-commit locally before. Normally, it will automatically check code grammar and correct code styles for your commited code. (1) In this **successful case**, it indicates that everything works well. No code grammar mistake and code style conforms to the configuration. Hence, no need to do further, you can push the local commit to remote codebase in the GitHub. @@ -86,20 +96,28 @@ Takeaway: Pasted Graphic 9 + Pasted Graphic 9 + The next step is to use `git status` and `git diff` to check the details in the corrected files to see what CI tool has done for you. Pasted Graphic 13 Pasted Graphic 14 + Pasted Graphic 14 + You would see that you need to use `git add` again. Because CI tool has modified your code , you need to do a standard git commit process again. Pasted Graphic 16 + Pasted Graphic 16 + Again, you need to run `git commit` again. Just use the previous same command. Now, it passes! Fancy is it? Until now, you are allowed to push the local commit to remote codebase in the GitHub. Pasted Graphic 17 + Pasted Graphic 17 + 14. Back to the **successful case**. Now, it is time to push your local **dev/Sany** branch to the remote **dev/Sany** branch. It may not created yet, but no worried, it will be shown later. Firstly, use `git pull origin main --rebase`. This command pulls the latest changes from the remote **main** branch and applies them to your local **dev/Sany** branch, while also rebasing your local changes on top of the new changes from the remote. (1) **No conflict case**: In this example, it indicates that there is no conflict with the remote **main** branch. Quite normally, sometimes, when you are coding in your own branch, the remote **main** branch is far ahead of yours. It is likely that there are conflicts existing so you need to resolve the conflicts before merge your remote **dev/Sany** branch into remote **main** branch. @@ -134,6 +152,8 @@ Takeaway: Pasted Graphic 5 + Pasted Graphic 5 + Once you finish pushing, you can use `git stash pop` to bring back the modified files into your working directory. For more information about **git stash** , plz google it. Pasted Graphic 6 diff --git a/docs/source/For Developer/Common Operations in Sphinx.md b/docs/source/For Developer/Common Operations in Sphinx.md new file mode 100644 index 00000000..d9916cc8 --- /dev/null +++ b/docs/source/For Developer/Common Operations in Sphinx.md @@ -0,0 +1,54 @@ +# Common Operations in Sphinx + +Takeaway ++ Installation - PyPi(windpows, CMD) ++ Installation - PyPi(windpows, Powershell) ++ Installation - Conda(windpows, waiting for update) ++ Installation - PyPi(MacOS/Linux, waiting for update) ++ Installation - Conda(MacOS/Linux, waiting for update) ++ Fast Build Sphinx + +1. Open the **CMD** terminal in the **Windows** and install the **Sphinx** package by the **Pypi**. The first step is to enter the **geochemistrypi** file and activate the virtual envirnment. Then use the **pip** command to install the **Sphinx** package. + +```None +cd geochemistry +conda activate your_env # Conda with Vscode is the most recommended way +pip install -U sphinx +``` + image + + image + +2. Open the **Powershell** terminal in the **Windows** and install the **Sphinx** package by the **Pypi**. The steps are close to the CMD way. + +image + + image + +3. The ***Sphinx*** ia a convenient tool for documentations in the projects managemnet. From the *[Getting start](https://www.sphinx-doc.org/en/master/tutorial/getting-started.html)* of the official ***[Sphinx documentations](https://www.sphinx-doc.org/en/master/index.html)***, we'd better to set a *README.rst* file in a project like: + +
+ imageimage +
+ +This time I just make a trail docs file. In fact, in a real project, we must write down the descriptions of the project. + +In addition, the *[Creating the documentation layout](https://www.sphinx-doc.org/en/master/tutorial/getting-started.html)* is also useful to set up a layout. The specific code is just: + +```None +sphinx-quickstart docs +``` + +*In this doc, the consequent screenshots are gained on the Powershell/Windows platform. The fast layout would be like:* + +image + +As you can see, after you write down the commands, some Chinese reflects are shown in the screen. The root can be set as you wish. + +*Then several parameters can be set in the Terminal:* + +image + +*Congratulations！Now you can start write in the index.rst file:* + +image diff --git a/docs/source/index.rst b/docs/source/index.rst index b62f4afd..fe669ef9 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -30,13 +30,31 @@ Welcome to Geochemistry π :caption: For Developer Developer Guide - Contributing + Docs Link + Local Deployment Docker Deployment Algorithm Functionality Addition Complete Pull Request + +.. toctree:: + :maxdepth: 4 + :caption: For Developer + + Developer Guide Docs Link + Local Deployment + Docker Deployment + Algorithm Functionality Addition + Complete Pull Request + +.. toctree:: + :maxdepth: 3 + :caption: Contributor + + Contributing + Indices and tables ==================