用sphinx 写文档

回复 收藏
sphinx http://sphinx-doc.org 是用python写的一个写文档的工具,阿铭的linux入门教程就是用该工具写出来的  http://study.lishiming.net  它不仅可以生成html网页还可以生成pdf电子书。

在CentOS上如何安装 sphinx?

首先sphinx新版本对python版本有要求,首先需要是python-2.6  所以如果您的centos是5.x版本是安装不了较新版本的。

1. 下载sphinx   http://pypi.python.org/packages/ ... e2a76ebedc76d8f71a3   如果该地址失效,请到官网 https://pypi.python.org/pypi/Sphinx#downloads

2.  安装 sphinx

tar zxvf  Sphinx-1.2b1.tar.gz
cd  Sphinx-1.2b1
python setup.py build
python setup.py install

3.  生成自己的第一个文档

sphinx-quickstart
根据自己需求填写相应项,y/n  都选y.  其中  
Source file suffix [.rst]:  
这一项要写成 .txt
  1. Welcome to the Sphinx 1.2b1 quickstart utility.
  2. Please enter values for the following settings (just press Enter to
  3. accept a default value, if one is given in brackets).
  4. Enter the root path for documentation.
  5. > Root path for the documentation [.]: /home/sphinx
  6. You have two options for placing the build directory for Sphinx output.
  7. Either, you use a directory "_build" within the root path, or you separate
  8. "source" and "build" directories within the root path.
  9. > Separate source and build directories (y/N) [n]: y
  10. Inside the root directory, two more directories will be created; "_templates"
  11. for custom HTML templates and "_static" for custom stylesheets and other static
  12. files. You can enter another prefix (such as ".") to replace the underscore.
  13. > Name prefix for templates and static dir [_]:
  14. The project name will occur in several places in the built documentation.
  15. > Project name: 跟阿铭学Linux
  16. > Author name(s): Aming
  17. Sphinx has the notion of a "version" and a "release" for the
  18. software. Each version can have multiple releases. For example, for
  19. Python the version is something like 2.5 or 3.0, while the release is
  20. something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
  21. just set both to the same value.
  22. > Project version: 2
  23. > Project release [2]: 2
  24. The file name suffix for source files. Commonly, this is either ".txt"
  25. or ".rst".  Only files with this suffix are considered documents.
  26. > Source file suffix [.rst]: .txt
  27. One document is special in that it is considered the top node of the
  28. "contents tree", that is, it is the root of the hierarchical structure
  29. of the documents. Normally, this is "index", but if your "index"
  30. document is a custom template, you can also set this to another filename.
  31. > Name of your master document (without suffix) [index]: index
  32. Sphinx can also add configuration for epub output:
  33. > Do you want to use the epub builder (y/N) [n]: y
  34. Please indicate if you want to use one of the following Sphinx extensions:
  35. > autodoc: automatically insert docstrings from modules (y/N) [n]: y
  36. > doctest: automatically test code snippets in doctest blocks (y/N) [n]: y
  37. > intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y
  38. > todo: write "todo" entries that can be shown or hidden on build (y/N) [n]: y
  39. > coverage: checks for documentation coverage (y/N) [n]: y
  40. > pngmath: include math, rendered as PNG images (y/N) [n]: y
  41. > mathjax: include math, rendered in the browser by MathJax (y/N) [n]: y
  42. Note: pngmath and mathjax cannot be enabled at the same time.
  43. pngmath has been deselected.
  44. > ifconfig: conditional inclusion of content based on config values (y/N) [n]: y
  45. > viewcode: include links to the source code of documented Python objects (y/N) [n]: y
  46. A Makefile and a Windows command file can be generated for you so that you
  47. only have to run e.g. `make html' instead of invoking sphinx-build
  48. directly.
  49. > Create Makefile? (Y/n) [y]: y
  50. > Create Windows command file? (Y/n) [y]: y
4. 写文档

进入  Root path for the documentation [.]:   定义的项目主目录,比如我的主目录为  /home/sphinx

cd   /home/sphinx
vim  source/index.txt

编辑索引页:
  1. .. toctree::
  2.    :maxdepth: 2
  3.    tets1
  4.    test2
  5.    test3
  6.    test4
然后编辑  test1.txt  test2.txt  ....

vim  source/test1.txt
vim source/test2.txt

编辑好所有文章后,生成 html 网页

make html  (需要在 /home/sphinx/) 执行
2013-05-31 09:53 举报
已邀请:
0

阿铭 管理员

赞同来自:

先安装texlive  用yum安装的版本较低,生成中文的pdf有问题,所以需要下载最新版本。
http://www.tug.org/texlive/acquire-netinstall.html

生成 pdf
make latex
make latexpdf

目前找了很多关于中文pdf的资料, 都试过,可就是不成功,所以目前暂时放弃了,以后有机会再来研究。

回复帖子,请先登录注册

退出全屏模式 全屏模式 回复
评分
可选评分理由: