[TOC]

使用sphinx、github、readthedocs搭建书环境

参考:https://www.jianshu.com/p/78e9e1b8553a

0、简介

GitHub Wiki,适合做知识整理,但排版一般,不方便本地查看。(第一次晓得这个功能的用途) GitBook,丑,慢。(???)

用 Sphinx 生成文档,GitHub 托管文档,再导入到 ReadtheDocs。

1、安装环境

pip install sphinx

Anaconda可能自带sphinx

2、创建工程

sphinx-quickstart

然后进行相应的配置: 输入y(默认n,如果n的话就无source文件夹) 项目名称 作者 版本号 语言(zh_CN)

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

使用tree命令可以看见树形结构。

最后使用命令:make html

3、切换主题(配置文件)

修改文件conf.py

html_theme = 'sphinx_rtd_theme'

也可以看见刚刚设置的相关配置,可以直接修改。 奇了怪了,一开始使用make html,第二次就不行了,需要安装主题包pip install sphinx_rtd_theme,但是安装失败了。

注意:需要安装这个主题,建议使用conda install sphinx_rtd_theme

4、配置markdown的编写

5、错误:WARNING: toctree contains reference to nonexisting document warnings

删除后面的:caption: Contents:,未找到保留的方法。

.. toctree::
   :maxdepth: 2
   :caption: Contents:

6、部署到readthedocs官网上

最终项目网站:https://ml-booknote.readthedocs.io

显示特点:左侧栏显示文章的一级标题,分级显示

7、后期维护使用

访问网站:https://ml-booknote.readthedocs.io readthedocs网站(使用github账号登录):https://readthedocs.org/ github仓库:https://github.com/HanKin2015/ML_BookNote.git

  • 在ML_BookNote\source\usage目录下添加新文章,支持md和rst文件
  • 还需要在ML_BookNote\source\index.rst里面添加新的文件。。。
  • 使用anaconda窗口执行make html即可
  • 上库:先将项目上传到git上,然后使用readthedocs的Build version即可

results matching ""

    No results matching ""