3.1 記錄自己的代碼和分析步驟
在生信學(xué)習(xí)中，我們經(jīng)常會寫一些代碼來幫助快速實(shí)現(xiàn)數(shù)據(jù)分析敌土。如何有效且便捷的記錄自己的代碼和數(shù)據(jù)分析步驟镜硕？這是一件值得思考的事情。
不能及時有效的記錄自己的代碼或者分析步驟返干，一段時間后就可能會忘掉谦疾。這樣一來，自己還需花大量時間去重新整理思路犬金。對生信學(xué)習(xí)來講念恍，這是不可取的六剥。良好的實(shí)驗(yàn)分析記錄習(xí)慣是非常重要的，盡管這可能會花掉一部分時間峰伙，但是其中的好處是不可估量的疗疟。
現(xiàn)在很多生信學(xué)習(xí)者喜歡用markdown去記錄自己的日常。markdown對于大部分使用者來說是友好的瞳氓。語法簡單策彤，容易掌握。市面上也出現(xiàn)了一些比較好用的markdown軟件匣摘，例如：CMD Markdown店诗。這里為了提升自己的文件逼格然后與諸如Read the Docs之類的接軌，我給大家介紹一下Jupyter notebook 和Sphinx這兩個神器音榜。
3.1.1 Jupyter notebook的安裝與使用
Jupyter notebook 想必大家都不陌生庞瘸，這里我簡單地給大家介紹一下它。 目前Jupyter notebook主要支持python2/3內(nèi)核赠叼， R內(nèi)核擦囊，Bash內(nèi)核還有Julia 內(nèi)核。對于它的安裝也相對比較簡單嘴办。如果你的電腦里已經(jīng)安裝了Python (2或者3）瞬场，你可以直接用pip對其進(jìn)行安裝。 如果你沒有安裝pip, 可以用以下代碼去安裝（已經(jīng)安裝的小伙伴可以跳過此步驟）
$ wget https://bootstrap.pypa.io/get-pip.py
$ python get-pip.py
安裝結(jié)束后涧郊，你可以用pip進(jìn)行對jupyter的安裝贯被。
$ pip install jupyter
對于bash內(nèi)核的支持，大家可以用以下代碼去安裝（僅限于Linux/MacOS系統(tǒng)）
$ pip install bash_kernel
$ python -m bash_kernel.install
一切準(zhǔn)備就緒后妆艘，大家就可以打開Jupyter notebook了
$ jupyter notebook
然后通過選擇跳出網(wǎng)頁右上角New 選項去建立例如bash文本彤灶。具體的寫作語句可以參考這里。在此我就不贅述了双仍。
3.1.2 Sphinx的安裝與使用
作為高端大氣上檔次的html轉(zhuǎn)化器，sphinx你值得擁有桌吃。 Sphinx提供了很多主題朱沃，可以幫助美化你的jupyter notebook文本并將它轉(zhuǎn)化成html網(wǎng)頁版。Read the Docs就是應(yīng)用sphinx來轉(zhuǎn)化docs的茅诱。 廢話不多講逗物，先看看怎么安裝它。
安裝之前請確保你的系統(tǒng)中已經(jīng)安裝了Pandoc.
- 對于MacOS用戶來說你可以下載
Pacdoc: https://github.com/jgm/pandoc/releases - 對于Linux用戶來說你可以下載
Pacdoc: https://pandoc.org/installing.html
完成以上安裝后瑟俭，你可以參考以下代碼去安裝sphinx
$ pip install pandoc
$ pip install pypandoc
$ pip install sphinx
$ pip install nbsphinx
$ pip install sphinx_rtd_theme
nbsphinx的使用手冊可以參考：http://nbsphinx.readthedocs.io
如何使用sphinx
$ mkdir -p docs
$ cd docs
$ sphinx-quickstart
你會看到這樣的信息：
Welcome to the Sphinx 1.6.7 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Enter the root path for documentation.
> Root path for the documentation [.]:
打回車鍵翎卓，你會看到
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]:
選擇y, 然后打回車鍵，你會看到
Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:
打回車鍵摆寄，你會看到
The project name will occur in several places in the built documentation.
> Project name:
填寫自己的project名字失暴，作者坯门，版本號，然后一直按回車鍵直到：
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]:
選擇y逗扒。然后接著回車鍵到最后古戴。你就建立一個屬于自己的project。具體的文件結(jié)構(gòu)如下：
.
├── Makefile
├── build
├── make.bat
└── source
├── _static
├── _templates
├── conf.py
└── index.rst
這里最重要的是你的conf.py和index.rst文件矩肩。
要想有效的利用sphinx, 你可以先把.ipynb文件轉(zhuǎn)換成.rst文件 （語法豐富多彩现恼，感興趣的可以自己直接寫.rst文件）.
$ ipython nbconvert --to rst /path/to/your/test.ipynb
轉(zhuǎn)化完成后將test.rst 文件拷貝到上面的sourcefolder。
下面就是對index.rst的設(shè)置了黍檩。
index.rst要求必須保留toctree 設(shè)置叉袍，其他不用的可以刪掉，具體如下：
====================================
Welcome to my sphinx documentation! ##給自己文檔起個名字
====================================
.. toctree::
:maxdepth: <int> ##可選任意數(shù)刽酱，如10.
:caption: xxxxxx ##標(biāo)題注釋喳逛，也可不填
test ##這里是你轉(zhuǎn)化的rst文件名字
接下來是conf.py的設(shè)置，可參考:
nbsphinx_execute = 'never'
nbsphinx_allow_errors = True
nbsphinx_prompt_width = 0
exclude_patterns = ['_build', '**.ipynb_checkpoints', 'Thumbs.db', '.DS_Store']
html_theme = 'sphinx_rtd_theme' ##主題很多肛跌，可自行選擇
html_theme_options = {'collapse_navigation': True}
sphinx有不少的主題艺配，你可以在sphinx-themes 瀏覽下載。
完成以上設(shè)置后衍慎，回到上一級 docs folder 里转唉，然后
$ make html
你的html文本就會出現(xiàn)在你的./build/html文件中。
下一講我將介紹如何免費(fèi)創(chuàng)建自己Read the docs稳捆，敬請關(guān)注赠法。
希望大家相互學(xué)習(xí)，多批評指正乔夯！
版權(quán)所有者 Andy. Twitter: @Yuxuan_Yuan; Wechat: yyx8671砖织；微信公眾號：生信人生
