3.1 记录自己的代码和分析步骤
在生信学习中，我们经常会写一些代码来帮助快速实现数据分析。如何有效且便捷的记录自己的代码和数据分析步骤？这是一件值得思考的事情。
不能及时有效的记录自己的代码或者分析步骤，一段时间后就可能会忘掉。这样一来，自己还需花大量时间去重新整理思路。对生信学习来讲，这是不可取的。良好的实验分析记录习惯是非常重要的，尽管这可能会花掉一部分时间，但是其中的好处是不可估量的。
现在很多生信学习者喜欢用markdown去记录自己的日常。markdown对于大部分使用者来说是友好的。语法简单，容易掌握。市面上也出现了一些比较好用的markdown软件，例如：CMD Markdown。这里为了提升自己的文件逼格然后与诸如Read the Docs之类的接轨，我给大家介绍一下Jupyter notebook 和Sphinx这两个神器。
3.1.1 Jupyter notebook的安装与使用
Jupyter notebook 想必大家都不陌生，这里我简单地给大家介绍一下它。 目前Jupyter notebook主要支持python2/3内核， R内核，Bash内核还有Julia 内核。对于它的安装也相对比较简单。如果你的电脑里已经安装了Python (2或者3），你可以直接用pip对其进行安装。 如果你没有安装pip, 可以用以下代码去安装（已经安装的小伙伴可以跳过此步骤）
$ wget https://bootstrap.pypa.io/get-pip.py
$ python get-pip.py
安装结束后，你可以用pip进行对jupyter的安装。
$ pip install jupyter
对于bash内核的支持，大家可以用以下代码去安装（仅限于Linux/MacOS系统）
$ pip install bash_kernel
$ python -m bash_kernel.install
一切准备就绪后，大家就可以打开Jupyter notebook了
$ jupyter notebook
然后通过选择跳出网页右上角New 选项去建立例如bash文本。具体的写作语句可以参考这里。在此我就不赘述了。
3.1.2 Sphinx的安装与使用
作为高端大气上档次的html转化器，sphinx你值得拥有。 Sphinx提供了很多主题，可以帮助美化你的jupyter notebook文本并将它转化成html网页版。Read the Docs就是应用sphinx来转化docs的。 废话不多讲，先看看怎么安装它。
安装之前请确保你的系统中已经安装了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。具体的文件结构如下：
.
├── Makefile
├── build
├── make.bat
└── source
├── _static
├── _templates
├── conf.py
└── index.rst
这里最重要的是你的conf.py和index.rst文件。
要想有效的利用sphinx, 你可以先把.ipynb文件转换成.rst文件 （语法丰富多彩，感兴趣的可以自己直接写.rst文件）.
$ ipython nbconvert --to rst /path/to/your/test.ipynb
转化完成后将test.rst 文件拷贝到上面的sourcefolder。
下面就是对index.rst的设置了。
index.rst要求必须保留toctree 设置，其他不用的可以删掉，具体如下：
====================================
Welcome to my sphinx documentation! ##给自己文档起个名字
====================================
.. toctree::
:maxdepth: <int> ##可选任意数，如10.
:caption: xxxxxx ##标题注释，也可不填
test ##这里是你转化的rst文件名字
接下来是conf.py的设置，可参考:
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 浏览下载。
完成以上设置后，回到上一级 docs folder 里，然后
$ make html
你的html文本就会出现在你的./build/html文件中。
下一讲我将介绍如何免费创建自己Read the docs，敬请关注。
希望大家相互学习，多批评指正！
版权所有者 Andy. Twitter: @Yuxuan_Yuan; Wechat: yyx8671；微信公众号：生信人生
网友评论