前言： 最近在讀很火的
tianshou（基於pytorch提供深度強化學習算法的簡易接口），兩個清華本科生做的。很規範、很優秀的項目。 做出來的項目，想要讓別人使用、維護、建立良性可持續社區，項目結構清晰、寫註釋、生成文檔是必不可少的。 我在GitHub上 watch 了該項目，現在項目文檔工作正如火如荼，我的郵件提示也常常響起：“你看看，人家清華巨佬們今天又在努力工作學習，剛剛又提交了一個 commit ，而你寫的幼兒園級別算法甚至都不收斂至最優解！”嗯… watch 了人家的項目，時刻提醒自己：已經很渣了，再不努力就被落下太遠了。說正題，通過閱讀這個正在生長的項目， 我學到了一個健康項目該有的文檔與測試規範 ：pep8、Sphinx、pytest與GitHub Action的集成。
強化學習算法接口集成的必要性
強化學習與傳統的“監督學習”、“非監督學習”不同，強化學習要時刻與環境/模型交互，以傳輸數據。這就不能簡單地將數據輸入，而要整理算法與數據的接口，將二者連接起來。
這個問題我在 https://blog.csdn.net/weixin_42815609/article/details/105318763 中簡單探討過。
所以可以看出，清華大佬做的東西不但牛逼、好用，還有意義，將幫助很多 DRL 入門者及很多離入門都很遠的渣渣（比如我）更好地學習並嘗試實踐 DRL 。
pep8
“PEP 是 Python Enhancement Proposal 的縮寫，翻譯過來就是 Python風格建議書”。PEP8 應該其第8章，標題爲 Style Guide for Python Code ，給出了代碼樣式（標準化、統一）的意見。
pep8 的大名我早就聽說過，起初我對其理解是這樣的：pep8 告訴我們縮進要有 4 個空格！
學了一些 python 後，我的理解是這樣的： pep8 告訴我們類名首字母大寫！
到現在，我才明白，pep8 大概是這樣的：
- pep8 確實對代碼風格、樣式做出了規範，
使代碼標準化，更易讀； - 但 pep8 真正牛逼之處在於，規範後的項目，其註釋、結構可以被 Sphinx 、pydoc 解析，也就意味着，
如果你只寫代碼文件，並且遵從 pep8 的規範在代碼之間寫註釋，那麼你的項目的說明文檔也就自動生成了！
Sphinx
清華巨佬應該是用 Sphinx 生成的 .rst文件，之後通過 make html 生成網頁文件再投到網上。整個過程全部自動化，符合程序員“懶惰”的美德。
你看上圖，清華大佬只要在代碼中加一些註釋（右），然後他在本地就能自動生成 html ；他上傳到服務器後，官網上就有了相應的說明文檔（左）！
下面是大佬寫的 Contributing guidelines ，我就是通過閱讀這個 .md 文件才知道、檢索、並學習到上述技術的。
Contributing
To install Tianshou in an “editable” mode, run
pip install -e .
in the main directory. This installation is removable by
python setup.py develop --uninstall
Additional dependencies for developments can be installed by
pip install ".[dev]"
Tests
This command will run automatic tests in the main directory
pytest test --cov tianshou -s
To run on your own GitHub Repo, enable the GitHub Action and it will automatically run the test.
PEP8 Code Style Check
We follow PEP8 python code style. To check, in the main directory, run:
flake8 . --count --show-source --statistics
Documents
Documents are written under the docs/ directory as RestructuredText (.rst) files. index.rst is the main page. A Tutorial on RestructuredText can be found here.
API References are automatically generated by Sphinx according to the outlines under
doc/api/ and should be modified when any code changes.
To compile docs into webpages, run
make html
under the docs/ directory. The generated webpages are in docs/_build and
can be viewed with browsers.
引用自：https://github.com/thu-ml/tianshou/blob/master/CONTRIBUTING.md
pytest與GitHub Action的集成
我一直不太理解什麼是 CI/CD 和 GitHub 的 workflow 是做什麼的，現在大概明白一些了：
- 在我看來，持續集成服務就是將合格的、寫完的新版代碼自動推出；
- 這其中可能涉及到一些動作（命令），而 GitHub Action 將其打包，不需要每次發佈新版本時都輸入這些命令；
- 現在算法工程師們將其用在算法測試上，比如上午提到的
pytest test --cov tianshou -s：To run on your own GitHub Repo, enable the GitHub Action and it will automatically run the test.
Piper Liu
2020-4-6 00:15:11
本來想零點前寫完的。不管怎麼說，還是應該早睡早起，晚安。