github 之 如何在项目中加入专业的文档说明
来源:互联网 发布:田众和时代网络 编辑:程序博客网 时间:2024/05/22 09:14
入门教程
http://www.liaoxuefeng.com/
前言
我们在github中常见一些项目有专门的文档说明,如django-tastypie.那这些文档是怎样生成的呢?
见http://django-tastypie.readthedocs.org/
使用Sphinx生成文档
Sphinx是一个基于Python的文档生成项目。最早只是用来生成Python的项目文档,但随着这个项目的逐渐完善,很多非Python的知名项目也采用Sphinx作为文档写作工具,甚至完全可以用Sphinx来写书。
引用一段Sphinx生成文档的优点包括:
丰富的输出格式: 支持输出为HTML,LaTeX (可转换为PDF), manual pages(man), 纯文本等若干种格式
完备的交叉引用: 语义化的标签,并对 函式,类,引文,术语以及类似片段消息可以自动化链接
明晰的分层结构: 轻松定义文档树,并自动化链接同级/父级/下级文章
美观的自动索引: 可自动生成美观的模块索引
精确的语法高亮: 基于 Pygments 自动生成语法高亮
开放的扩展: 支持代码块的自动测试,自动包含Python 的模块自述文档,等等
其实上面这么多功能,最本质的核心还是在于Sphinx采用了轻量级标记语言中的reStructuredText作为文档写作语言。reStructuredText是类似Wiki,Markdown的一种纯文本标记语言,所有Sphinx的文档其实都是扩展名为rst的纯文本文件,然后经过转换器转换为各种输出格式,并且可以配合版本控制系统轻松实现Diff。
readthedocs
文档托管的平台,能够和常用的GIT阵营的github,HG阵营的Bitbucket交互
把github中的文档的代码仓库导入到readthedocs
首先在github->repo->Admin-ServiceHooks->ReadTheDocs,激活这个选项。
readthedocs->Import 按照上边的有关字段的提示填写清楚,必要的Name Author Version Repo……,这里注意 conf.py 路径要填写正确(source/conf.py),提交。
sphinx
文档书写利器,使用的是reStructuredText格式,reStructuredText简明教程 和使用sphinx笔记
sphinx安装过程
Sphinx安装首先安装好Python环境,建议选择Pyhon2.7.3,并且把Python及Python/Scripts目录加入环境变量,然后只需要一行命令即可pip install sphinx安装完毕之后,进入任意目录,运行sphinx-quickstart会进入一个设置向导,根据向导一步一步设置文档项目,其实必填项只有项目名称,作者和版本,其他设置都可以一路回车: 文档根目录(Root path for the documentation),默认为当前目录(.) 是否分离文档源代码与生成后的文档(Separate source and build directories): y 模板与静态文件存放目录前缀(Name prefix for templates and static dir):_ 项目名称(Project name) : EvaEngine 作者名称(Author name):AlloVince 项目版本(Project version) : 1.0.1 文档默认扩展名(Source file suffix) : .rst 默认首页文件名(Name of your master document):index 是否添加epub目录(Do you want to use the epub builder):n 启用autodoc|doctest|intersphinx|todo|coverage|pngmath|ifconfig|viewcode:n 生成Makefile (Create Makefile):y 生成windows用命令行(Create Windows command file):y最后会生成Sphinx一个文档项目必需的核心文件,包括:readthedocs│ make.bat│ Makefile├─build└─source │ conf.py │ index.rst ├─_static └─_templates
如果向导中的所有设置都保存在conf.py中,可以随时调整。Sphinx生成文档source目录就是存放文档源代码的目录,默认的索引页面为index.rst我们尝试来写作第一篇文档,在source目录下建立helloworld.rst,内容为:Hello World ===========同时编辑index.rst对应部分为.. toctree:: :maxdepth: 1 helloworld然后在当前目录下运行make html会看到build目录下会生成HTML格式的文档。同理我们可以make letex生成LeTex以及其他格式。
- github 之 如何在项目中加入专业的文档说明
- github 之 如何在项目中加入coverage
- 如何在XHTML文档中加入CSS
- 项目开发中如何写说明文档
- 如何删除在Github中创建的项目
- 关于在基于Struts构架的Java Web项目中加入ICTCLAS分词两点说明
- 在webstorm中如何关联github项目
- 我是如何在GitHub上开源一个项目的(截图说明)
- 我是如何在GitHub上开源一个项目的(截图说明)
- 我是如何在GitHub上开源一个项目的(截图说明)
- 我是如何在GitHub上开源一个项目的(截图说明)
- 我是如何在GitHub上开源一个项目的(截图说明) (VS2010可以安装git插件)
- 在tomcat中如何配置访问的时候不需要在URL中加入项目名
- 在tomcat中如何配置访问的时候不需要在URL中加入项目名
- 【GitHub】如何在自己的项目中添加"Fork me on GitHub"标识
- 在Java中生成专业的公文文档
- 如何在github上传自己的项目
- 如何在github上传自己的项目
- Rabin_Miller
- 2013秋13级预备队集训练习1 L - Linear Cellular Automata
- 重构学习笔记
- 利用WPF建立自适应窗口大小布局的WinForm窗口31
- 运行nslookup出错,bind9启动提示
- github 之 如何在项目中加入专业的文档说明
- 如何在Linux系统下进行C++程序开发
- 最牛B的编码套路
- 初学UI之关灯游戏
- VC 自创画布绘制
- MYSQL 的常用方法
- 退役了
- sublime配置全攻略
- OpenRisc-18-or1200下linux简单gpio字符设备驱动