美文网首页产品经理Python技术总结
如何用 ReadtheDocs、Sphinx 快速搭建写书环境

如何用 ReadtheDocs、Sphinx 快速搭建写书环境

作者: 不求来生 | 来源:发表于2016-03-28 08:41 被阅读7445次

    参加的数据科学班今天结束了,但还有很多疑难点没搞清楚,很多收获也没整理。课程结束后想补写下笔记,做下查遗补漏,心想,与其写笔记,不如写成一本书的形式,更美观,也更系统。

    现有的写电子书的方式,有以下几个解决方案,优劣势也很明显。

    • 自有博客,跟散文堆在一起,不便索引。
    • GitHub Wiki,适合做知识整理,但排版一般,不方便本地查看。
    • GitBook,丑,慢。

    经过一些比较和调查,最终锁定 Sphinx + GitHub + ReadtheDocs 作为文档写作工具。用 Sphinx 生成文档,GitHub 托管文档,再导入到 ReadtheDocs。

    Sphinx 是一个基于 Python 的文档生成工具,最早只是用来生成 Python 官方文档,随着工具的完善,越来越多的知名的项目也用他来生成文档,甚至完全可以用他来写书,我最初被他所震撼,也是因为看到了这本书 Linux 工具教程

    引用几点 Sphinx 的优势:

    • 丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX (可以打印PDF版本), manual pages(man 文档), 纯文本
    • 完备的交叉引用: 语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息
    • 明晰的分层结构: 可以轻松的定义文档树,并自动化链接同级/父级/下级文章
    • 美观的自动索引: 可自动生成美观的模块索引
    • 精确的语法高亮: 基于 Pygments 自动生成语法高亮

    更多介绍,请看此处:Sphinx 使用手册

    注:以下操作默认你熟悉命令行操作。

    1. 安装 Sphinx

    Mac 系统下安装极简,一行代码搞定

    brew cask install sphinx
    

    pip install sphinx
    

    我因为之前安装过 Anaconda,自带了 sphinx,便省略这步了。更多安装方法,请看此处:Install Sphinx

    2. 创建工程

    创建工程也就是创建文档。这步很简单,进入需要创建工程的目录,比如我的是 /Users/Scott/Documents/2.创造乐趣, 创建一个名为 DataBook 的文件夹,你可以用别的你想用的名字。

    创建:

    ➜  2.创造乐趣 pwd
    /Users/Scott/Documents/2.创造乐趣
    ➜  2.创造乐趣 mkdir BookData
    ➜  2.创造乐趣 ls
    1.keynote 2.技术    BookData  映射
    

    BookData 创建好了,进入该目录:

    ➜  2.创造乐趣 cd BookData
    

    输入sphinx-quickstart,接下来程序会提示你输入一些选项,基本上按 Return 就好了,有些地方看提示注意下,不懂的话可以参考这里:建立sphinx工程

    完成之后,

    ➜  BookData git:(master) ✗ ls
    Makefile build    make.bat source
    

    可以看到有4个文件:

    • build 目录 运行make命令后,生成的文件都在这个目录里面
    • source 目录 放置文档的源文件
    • make.bat 批处理命令
    • makefile

    基本完成,使用 make html 命令就可以生成html形式的文档了。

    配置(conf.py)

    如果没有什么特殊需要,我觉得 Sphinx 没啥好配的,改个主题就好了,个人极其喜欢ReadtheDoc的主题。很简单,把 conf.py 里面的这句:

    html_theme = 'alabaster'
    

    换成

    html_theme = 'sphinx_rtd_theme'
    

    将 Sphnix 生成的文档和配置 push 到远程 github

    ➜  BookData git init
    ➜  BookData git add .
    ➜  BookData git commit -m "sphinx start"
    ➜  BookData git remote add origin https://github.com/[yourusename]/[yourrepository].git
    ➜  BookData git push origin master
    

    注意:[yourusename]/[yourrepository] 换成你的 github 名和仓库名。

    3. 导入到 ReadtheDocs

    • GitHub 里选择仓库,然后依次点击 Setting => Webhooks & Service => Add service => ReadTheDocs,激活这个选项。

    • 到 ReadtheDocs import 这个仓库,导入成功后,点击阅读文档,便可看到 Web 效果了。

    4. 配置目录结构

    到了这一步,基本上已经搭建了,但这个时候直接写文档是还不够的。目录结构需要配置下。

    假如我要添加两个文档 example.rst 和 rest_eazy.rst 到索引 index.rst 里:

    .. toctree::
       :maxdepth: 2
    
       example
       rest_eazy
    

    make html后,效果如下:

    会发现明明是2个文档,左边却 有 3个标题,因为主索引是按一级标题的数量来索引的,所以这种方式不可取,标题一多会很乱,好的办法是创建二级索引:

    因为我要建的板块是3个,分别为数据科学「入门篇」、「基础篇」、「工具篇」,所以先把主索引 index.rst 改为:

    目录:
    ^^^^^
    
    .. toctree::
        :maxdepth: 2
        :glob:
        
        beginning/index
        base/index
        tool/index
    

    然后在 source 目录下创建 3个目录 ,每个目录下创建一个 index.rst 文件,也就是二级索引文件。

    mkdir beginning base tool
    touch beginning/index.rst base/index.rst tool/inde.rst 
    

    做完这步后,把书的大纲理一下,写到 BookData 目录底下的 README.md 文件里:

    # Python 和数据科学
    
    ### 全书目录:
    
    入门篇:
    
    - Linux
    - ipython
    - 数值计算(Numpy)
    - 数据绘图(Matplotlib)
    - 数据绘图(Seabornd)
    
    

    参照目录创建文件,如 入门篇,则在 beginning 目录下创建如下文件:

    touch 01_linux.rst 02_ipython.rst 03_numpy.rst 04_matplotlib.rst 05_seaborn.rst
    

    每个文件里写上 一级标题,然后检查下:

    ➜  BookData git:(master) ✗ ls source/beginning
    01_linux.rst      03_numpy.rst      05_seaborn.rst
    02_ipython.rst    04_matplotlib.rst index.rst
    ➜  BookData git:(master) ✗ cat source/beginning/*
    Linux 基础
    =========================
    
    Jupyter 基础
    =========================
    
    数值计算(Numpy)
    =========================
    
    数据绘图(Matplotlib)
    =========================
    
    数据绘图(Seaborn)
    =========================
    

    然后把文件名添加到二级索引 beginning/index 里

    入门篇
    ==========
    
    这一部分主要介绍数据科学的入门内容;\
    包含数据科学的基础工具,如:Jupyter、Linux,以及 Python 基本的数据科学包 Numpy,画图包 Matplotlib;
    
    
    .. toctree::
        :maxdepth: 2
        :numbered: 2
    
        01_linux
        02_ipython
        03_numpy
        04_matplotlib
        05_seaborn
    

    同理于 base 和 tool 目录,都完成之后会是下图的效果:


    链接:BookData, 有三个索引,下一个,上一个都非常顺畅。

    其他

    reStructureText 语法很简单,不建议刻意去学,如果习惯用 Markdown,建议用 pandoc 一键转化即可.

    相关文章

      网友评论

      • 魔法先生:Note: GitHub Services are being deprecated. Please contact your integrator for more information on how to migrate or replace a service with webhooks or GitHub Apps.

        可不可以更新下部署文档呢
      • 孙大脸:请问下三级目录是怎么添加的呢?
      • 谦言忘语:不是很明白这个东西。如果是多人编辑,是不是每个人的电脑都需要安装才能用?
        不求来生:@谦言忘语 建议先熟悉一下 Git
      • bendan33:请问, 如果有自己的域名, 主机。如何让文档不挂在ReadtheDocs 的域名下, 用自己的主机和域名呢?但有同样的模板效果。
        lebronzhen:生成本地的之后,直接挂上去就行
      • 洛奇洛:如果有自己申请的linux服务器,应该怎么搭建这种博客呢?
        洛奇洛:@rockywang 嗯嗯已经搭建好了 以后写文档就这么干了
        不求来生:@rockywang 如果有 Linux Web 服务器,应该是可以实现的,方法是一样的,等于说需要一个 ip 地址访问你服务器上 Sphnix 生成的 html 文件。
        洛奇洛:@rockywang 不用github
      • 洛奇洛:喜欢这样详细的文章 少走弯路 谢谢
      • 妙宗舶攸:好棒哦!
      • robo_one:博客我用github+jekyll
        不求来生:@robo_one 一样

      本文标题:如何用 ReadtheDocs、Sphinx 快速搭建写书环境

      本文链接:https://www.haomeiwen.com/subject/ddsjlttx.html