利用Sphinx编写文档
来源:互联网 发布:胡楚靓的淘宝店假货 编辑:程序博客网 时间:2024/06/01 09:11
利用Sphinx编写文档
1、Sphinx简介和使用理由
=================
Sphinx是一个用Python语言编写而成的文档编写工具。用Sphinx编写文档的时候,用户只需要编写符合Sphinx格式要求的纯文本源文件,然后通过Sphinx的命令就可以把纯文本源文件编译成html、pdf等常用格式的文档,这样就实现了通过文本文件自动生成html、pdf等格式文档的功能。
编写文档直接用Word不就是挺好的吗?为什么又要用Sphinx来写纯文本格式的文档呢?
这是因为Sphinx中的文本格式文档可以用版本控制系统跟踪它的变更,同时呢,它又可以非常轻松地生成多种的目标文档格式,比如编写一份Sphinx文档,然后通过工具就用这一份文档生成html、pdf、epub等其他格式的文档了,编写一种文本格式的文档,可以得到很多种其他格式的文档。
然而,word想要转成html就没有那么容易了,而且word文件是二进制文件,所以无法用版本控制系统来跟踪变更。
2、Sphinx在Windows下的安装
===================
Sphinx是用Python语言写成的软件,所以在安装Sphinx之前首要先要安装Python。
Python安装好之后,可以通过Python自带的Pip工具来安装Sphinx。只需要下面这一条命令,就可以完成Sphinx的安装:
pip
install
Sphinx
3、利用Sphinx制作文档的一般步骤
=====================
一般情况下,用Sphinx来写文档的时候,首先要创建一个Sphinx工程,就像要编写C语言程序在IDE中要建一个工程是一样的道理。建好工程,之后就可以往这个工程中写自己的文档源文件了。源文件编写完成后,就可以生成目标格式的文档了,如果想要html格式就用相应的命令,想要pdf格式也可以用对应的命令来生成。
所以,通常就这么三步:
(1)建文档项目
(2)写文档源文件
(3)编译生成目标格式的文档
4、Sphinx基础知识
============
这里简单介绍一些Sphinx的文档的基本编写知识。详细的情况可以参考《参考资料1》和中文版的《Sphinx使用手册》。
5、发布文档
========
发布文档是什么意思呢?因为Sphinx写文档可以编译成html格式,那么html格式的文档,就可以发布在网上,大家像看网站那样看文档。有一个叫readthedocs.org的网站就可以托管Sphinx生成的文档。
详情可以参考《参考资料4》
参考资料
1、https://www.ibm.com/developerworks/cn/opensource/os-sphinx-documentation/
2、http://www.jianshu.com/p/56515db85690
3、http://zh-sphinx-doc.readthedocs.io/en/latest/contents.html
4、http://avnpc.com/pages/writing-best-documentation-by-sphinx-github-readthedocs
- 利用Sphinx编写文档
- Sphinx-doc编写文档
- 利用Sphinx轻松生成python代码的文档
- 利用Sphinx轻松生成python代码的文档
- 使用sphinx写文档
- Sphinx.conf配置文档
- sphinx文档工具
- Sphinx 文档工具
- python 文档生成器 sphinx
- sphinx配置文档
- 用sphinx写文档
- coreseek/sphinx文档摘要
- sphinx使用整理文档
- sphinx自动化文档
- sphinx使用整理文档
- Sphinx 文档例子
- Sphinx API文档例子
- 利用.NET 类编写 XML 文档
- ubuntu: 查看 内存
- 面试题17:合并两个排序的链表
- 线程接收和发送
- mysql中的共享锁和排他锁
- 登录验证码实现逻辑
- 利用Sphinx编写文档
- Java中this和super的用法
- 01进制之间的概述与转换(二,八,十,十六进制)
- java面向对象-匿名对象
- 欢迎使用CSDN-markdown编辑器
- Python序列简介
- 西瓜书学习
- JavaWeb(二)随笔 介绍一下onchange 以及常见的一些调试技巧
- 指针的运算