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；微信公众号：生信人生