[文档]请问大家用什么系统来做帮助文档？我现在在学sphinx，被中文化郁闷了

16 views
Skip to first unread message

jun lin

unread,
Dec 30, 2009, 9:08:15 PM12/30/09
to pyth...@googlegroups.com
dear all:
请问是否有谁整理过中文使用sphinx的文档？
google 了一下，结果找到的都是索引系统的资料。
官方的资料没有看到很详细的中文化帮助。

现在要写帮助文档，和程序一起发布。
大家一般用什么来做帮助文档的？

jun lin

unread,
Dec 30, 2009, 9:10:19 PM12/30/09
to pyth...@googlegroups.com
遇到的第一个问题：sphinx默认用UTF-8，
我用emacs的，结果保存为系统默认的字符编码，
后来在rst文件头上面加上:: -*- coding:utf-8 -*-就OK了。
不知道怎么把emacs的编码改过来。。。

还有就是，新建了一个 关于.rst，结果就编译出错了：

writing output... [100%] 关于
e:\workspace\python\sphinx\source\index.rst:10: (WARNING/2) toctree references unknown document u'\u5173\u4e8e'
e:\workspace\python\sphinx\source\关于.rst:: WARNING: document isn't included in any toctree

Exception occurred:
  File "C:\Python26\lib\site-packages\jinja2\utils.py", line 752, in escape
    return Markup(unicode(s)
UnicodeDecodeError: 'ascii' codec can't decode byte 0xb9 in position 9: ordinal not in range(128)


2009/12/31 jun lin <linjun...@gmail.com>

机械唯物主义

unread,
Dec 30, 2009, 9:26:41 PM12/30/09
to python-cn`CPyUG`华蟒用户组(中文Py用户组)
google group终于可以用了，找到了相关的文档：
http://wiki.woodpecker.org.cn/moin/DocumentUsageSphinx

On Dec 31, 10:10 am, jun lin <linjunhal...@gmail.com> wrote:
> 遇到的第一个问题：sphinx默认用UTF-8，
> 我用emacs的，结果保存为系统默认的字符编码，
> 后来在rst文件头上面加上:: -*- coding:utf-8 -*-就OK了。
> 不知道怎么把emacs的编码改过来。。。
>
> 还有就是，新建了一个 关于.rst，结果就编译出错了：
>
> writing output... [100%] 关于
> e:\workspace\python\sphinx\source\index.rst:10: (WARNING/2) toctree
> references unknown document u'\u5173\u4e8e'
> e:\workspace\python\sphinx\source\关于.rst:: WARNING: document isn't included
> in any toctree
>
> Exception occurred:
> File "C:\Python26\lib\site-packages\jinja2\utils.py", line 752, in escape
> return Markup(unicode(s)
> UnicodeDecodeError: 'ascii' codec can't decode byte 0xb9 in position 9:
> ordinal not in range(128)
>

> 2009/12/31 jun lin <linjunhal...@gmail.com>

jun lin

unread,
Dec 30, 2009, 9:34:48 PM12/30/09
to python-cn`CPyUG`华蟒用户组
现在遇到2个问题：
1如何中文化？ next，previous都是英文的。

2如何生成pdf，我安装的是pythonxy，sphinx, rst2pdf
设置extensions = ['rst2pdf.pdfbuilder',]
运行：
sphinx-build -b pdf -d build/doctrees   source build/pdf

pdf没有生成，提示：

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
build succeeded, 22 warnings.
Making output directory...
e:\workspace\python\sphinx\source\intro.rst:1: WARNING: undecodable source characters, replacing with "?": '>>>\xbd<<<\xe9\xc9\xdc'
e:\workspace\python\sphinx\source\intro.rst:1: WARNING: undecodable source characters, replacing with "?": '\xbd>>>\xe9\xc9\xdc<<<'
e:\workspace\python\sphinx\source\intro.rst:4: WARNING: undecodable source characters, replacing with "?": 'N3130>>>\xbe<<<\xcd\xca\xc7\xba\xc3\xa3\xac\xbe\xcd\xca\xc7\xba\xc3\xd1\xbd\xbe\xcd\xca\xc7\xba\xc3\xa1\xa3'
e:\workspace\python\sphinx\source\intro.rst:4: WARNING: undecodable source characters, replacing with "?": 'N3130\xbe>>>\xcd\xca<<<\xc7\xba\xc3\xa3\xac\xbe\xcd\xca\xc7\xba\xc3\xd1\xbd\xbe\xcd\xca\xc7\xba\xc3\xa1\xa3'
e:\workspace\python\sphinx\source\intro.rst:4: WARNING: undecodable source characters, replacing with "?": 'N3130\xbe\xcd\xca\xc7\xba\xc3\xa3>>>\xac<<<\xbe\xcd\xca\xc7\xba\xc3\xd1\xbd\xbe\xcd\xca\xc7\xba\xc3\xa1\xa3'
e:\workspace\python\sphinx\source\intro.rst:4: WARNING: undecodable source characters, replacing with "?": 'N3130\xbe\xcd\xca\xc7\xba\xc3\xa3\xac>>>\xbe<<<\xcd\xca\xc7\xba\xc3\xd1\xbd\xbe\xcd\xca\xc7\xba\xc3\xa1\xa3'
e:\workspace\python\sphinx\source\intro.rst:4: WARNING: undecodable source characters, replacing with "?": 'N3130\xbe\xcd\xca\xc7\xba\xc3\xa3\xac\xbe>>>\xcd\xca<<<\xc7\xba\xc3\xd1\xbd\xbe\xcd\xca\xc7\xba\xc3\xa1\xa3'
e:\workspace\python\sphinx\source\intro.rst:4: WARNING: undecodable source characters, replacing with "?": 'N3130\xbe\xcd\xca\xc7\xba\xc3\xa3\xac\xbe\xcd\xca\xc7\xba>>>\xc3\xd1<<<\xbd\xbe\xcd\xca\xc7\xba\xc3\xa1\xa3'
e:\workspace\python\sphinx\source\intro.rst:4: WARNING: undecodable source characters, replacing with "?": 'N3130\xbe\xcd\xca\xc7\xba\xc3\xa3\xac\xbe\xcd\xca\xc7\xba\xc3\xd1>>>\xbd<<<\xbe\xcd\xca\xc7\xba\xc3\xa1\xa3'
e:\workspace\python\sphinx\source\intro.rst:4: WARNING: undecodable source characters, replacing with "?": 'N3130\xbe\xcd\xca\xc7\xba\xc3\xa3\xac\xbe\xcd\xca\xc7\xba\xc3\xd1\xbd>>>\xbe<<<\xcd\xca\xc7\xba\xc3\xa1\xa3'
e:\workspace\python\sphinx\source\intro.rst:4: WARNING: undecodable source characters, replacing with "?": 'N3130\xbe\xcd\xca\xc7\xba\xc3\xa3\xac\xbe\xcd\xca\xc7\xba\xc3\xd1\xbd\xbe>>>\xcd\xca<<<\xc7\xba\xc3\xa1\xa3'
e:\workspace\python\sphinx\source\intro.rst:4: WARNING: undecodable source characters, replacing with "?": 'N3130\xbe\xcd\xca\xc7\xba\xc3\xa3\xac\xbe\xcd\xca\xc7\xba\xc3\xd1\xbd\xbe\xcd\xca\xc7\xba\xc3\xa1>>>\xa3<<<'
e:\workspace\python\sphinx\source\intro.rst:6: WARNING: undecodable source characters, replacing with "?": '\xca\xb9>>>\xd3\xc3<<<\xb7\xbd\xb7\xa8'
e:\workspace\python\sphinx\source\intro.rst:6: WARNING: undecodable source characters, replacing with "?": '\xca\xb9\xd3\xc3>>>\xb7<<<\xbd\xb7\xa8'
e:\workspace\python\sphinx\source\intro.rst:6: WARNING: undecodable source characters, replacing with "?": '\xca\xb9\xd3\xc3\xb7>>>\xbd<<<\xb7\xa8'
e:\workspace\python\sphinx\source\intro.rst:6: WARNING: undecodable source characters, replacing with "?": '\xca\xb9\xd3\xc3\xb7\xbd>>>\xb7<<<\xa8'
e:\workspace\python\sphinx\source\intro.rst:6: WARNING: undecodable source characters, replacing with "?": '\xca\xb9\xd3\xc3\xb7\xbd\xb7>>>\xa8<<<'
e:\workspace\python\sphinx\source\intro.rst:9: WARNING: undecodable source characters, replacing with "?": '>>>\xb4<<<\xf2\xbf\xaa\xbe\xcd\xbf\xc9\xd2\xd4\xd3\xc3'
e:\workspace\python\sphinx\source\intro.rst:9: WARNING: undecodable source characters, replacing with "?": '\xb4\xf2\xbf\xaa\xbe\xcd\xbf>>>\xc9\xd2<<<\xd4\xd3\xc3'
e:\workspace\python\sphinx\source\intro.rst:9: WARNING: undecodable source characters, replacing with "?": '\xb4\xf2\xbf\xaa\xbe\xcd\xbf\xc9\xd2>>>\xd4\xd3<<<\xc3'
e:\workspace\python\sphinx\source\intro.rst:9: WARNING: undecodable source characters, replacing with "?": '\xb4\xf2\xbf\xaa\xbe\xcd\xbf\xc9\xd2\xd4\xd3>>>\xc3\n<<<'
WARNING: "pdf_documents" config value references unknown document contents

2009/12/31 机械唯物主义 <linjun...@gmail.com>
--
来自: `python-cn`:CPyUG ~ 华蟒用户组 | 发言:pyth...@googlegroups.com
退订: http://tinyurl.com/45a9tb //针对163/qq邮箱:http://tinyurl.com/4dg6hc
详情: https://groups.google.com/group/python-cn
严正: 理解列表! 智慧提问! http://wiki.woodpecker.org.cn/moin/AskForHelp

jun lin

unread,
Dec 30, 2009, 9:39:49 PM12/30/09
to python-cn`CPyUG`华蟒用户组
大家有解法的话，请大大们加到http://wiki.woodpecker.org.cn/moin/DocumentUsageSphinx里面。。。
恩，只读的。。

2009/12/31 jun lin <linjun...@gmail.com>

Zoom.Quiet

unread,
Dec 30, 2009, 9:47:34 PM12/30/09
to pyth...@googlegroups.com
2009/12/31 jun lin <linjun...@gmail.com>:

> 大家有解法的话，请大大们加到http://wiki.woodpecker.org.cn/moin/DocumentUsageSphinx里面。。。
> 恩，只读的。。
>
为防止 Spam 有ACL 的，你申请就好
http://wiki.woodpecker.org.cn/moin/WoodpeckerAclDefine

--
http://zoomquiet.org 人生苦短? Pythonic!
Free as in Freedom! 哲思社区:http://zeuux.com

刘鑫

unread,
Dec 30, 2009, 9:48:44 PM12/30/09
to python-cn


2009/12/31 jun lin <linjun...@gmail.com>

遇到的第一个问题：sphinx默认用UTF-8，
我用emacs的，结果保存为系统默认的字符编码，
后来在rst文件头上面加上:: -*- coding:utf-8 -*-就OK了。
不知道怎么把emacs的编码改过来。。。

(set-language-environment 'UTF-8)
(set-locale-environment "UTF-8")

 

还有就是，新建了一个 关于.rst，结果就编译出错了：

writing output... [100%] 关于
e:\workspace\python\sphinx\source\index.rst:10: (WARNING/2) toctree references unknown document u'\u5173\u4e8e'
e:\workspace\python\sphinx\source\关于.rst:: WARNING: document isn't included in any toctree

Exception occurred:
  File "C:\Python26\lib\site-packages\jinja2\utils.py", line 752, in escape
    return Markup(unicode(s)
UnicodeDecodeError: 'ascii' codec can't decode byte 0xb9 in position 9: ordinal not in range(128)


2009/12/31 jun lin <linjun...@gmail.com>

dear all:
请问是否有谁整理过中文使用sphinx的文档？
google 了一下，结果找到的都是索引系统的资料。
官方的资料没有看到很详细的中文化帮助。

现在要写帮助文档，和程序一起发布。
大家一般用什么来做帮助文档的？

--
来自: `python-cn`:CPyUG ~ 华蟒用户组 | 发言:pyth...@googlegroups.com
退订: http://tinyurl.com/45a9tb //针对163/qq邮箱:http://tinyurl.com/4dg6hc
详情: https://groups.google.com/group/python-cn
严正: 理解列表! 智慧提问! http://wiki.woodpecker.org.cn/moin/AskForHelp



--
每一行代码都应该出自我手，工具可以帮我写，但不能替我写，更不能替我思考。
……

劉鑫
March.Liu

jun lin

unread,
Dec 30, 2009, 10:02:41 PM12/30/09
to pyth...@googlegroups.com
设置之后，windows shell变成了乱码。。。
好吧，为什么XP不是UTF-8的呢。。。为什么呢。。。。

2009/12/31 刘鑫 <marc...@gmail.com>

刘鑫

unread,
Dec 30, 2009, 10:05:37 PM12/30/09
to python-cn


2009/12/31 jun lin <linjun...@gmail.com>

设置之后，windows shell变成了乱码。。。
好吧，为什么XP不是UTF-8的呢。。。为什么呢。。。。

对吖，在Windows下面是这样，你可以试试写个钩子，在shell/eshell中使用系统编码。

jun lin

unread,
Dec 30, 2009, 10:07:34 PM12/30/09
to pyth...@googlegroups.com
将就了，反正都是用gnu工具链。。。

roboter

unread,
Dec 30, 2009, 10:14:09 PM12/30/09
to pyth...@googlegroups.com
如果是html帮助，可以试试django的模板。

帮助内容就写在模板文件中，写帮助文件的人只需要了解一些模板语法和公司内部预定义的规则，帮助可以交给市场或者其他非程序员去干的。

当然程序员要干的是：写一个很小的工具，定义模板的block，把这些模板生成html文件。

俺用这个方法写了二十页的帮助，修改起来很简单了，想怎么弄就怎么弄。

2009/12/31 jun lin <linjun...@gmail.com>

--

Zoom.Quiet

unread,
Dec 30, 2009, 10:17:58 PM12/30/09
to pyth...@googlegroups.com
2009/12/31 jun lin <linjun...@gmail.com>:
> 现在遇到2个问题：
> 1如何中文化？ next，previous都是英文的。
>
关于本书的编写 — 用Python做科学计算 v1 documentation
http://hyry.dip.jp/pydoc/pydoc_write_tools.html
使用模板

> 2如何生成pdf，我安装的是pythonxy，sphinx, rst2pdf

http://wiki.woodpecker.org.cn/moin/UsageSphinxExPdf

> 设置extensions = ['rst2pdf.pdfbuilder',]
> 运行：
> sphinx-build -b pdf -d build/doctrees   source build/pdf
>

--
http://zoomquiet.org 人生苦短? Pythonic!
过程改进乃是催生可促生靠谱的人的组织! (ProcessEnhancement keeps evolving organizations
which promoting people b...
gs

jun lin

unread,
Dec 30, 2009, 10:23:33 PM12/30/09
to pyth...@googlegroups.com
不会是刚才写的吧？？？？？？？

2009/12/31 Zoom.Quiet <zoom....@gmail.com>
2009/12/31 jun lin <linjun...@gmail.com>:
> 现在遇到2个问题：
> 1如何中文化？ next，previous都是英文的。
>
关于本书的编写 -- 用Python做科学计算 v1 documentation

http://hyry.dip.jp/pydoc/pydoc_write_tools.html
使用模板

> 2如何生成pdf，我安装的是pythonxy，sphinx, rst2pdf

http://wiki.woodpecker.org.cn/moin/UsageSphinxExPdf

> 设置extensions = ['rst2pdf.pdfbuilder',]
> 运行：
> sphinx-build -b pdf -d build/doctrees   source build/pdf
>



--
http://zoomquiet.org 人生苦短? Pythonic!
过程改进乃是催生可促生靠谱的人的组织! (ProcessEnhancement keeps evolving organizations
which promoting people b...
gs

--

Zoom.Quiet

unread,
Dec 30, 2009, 10:27:01 PM12/30/09
to pyth...@googlegroups.com
2009/12/31 jun lin <linjun...@gmail.com>:
> 不会是刚才写的吧？？？？？？？
>
http://wiki.woodpecker.org.cn/moin/UsageSphinxExPdf?action=info

usage 7-zip to replace WinRAR/WinZip; You can get the truely Freedom 4 software.

limodou

unread,
Dec 30, 2009, 10:30:17 PM12/30/09
to pyth...@googlegroups.com
升级后我不是管理员了？


--
I like python!
UliPad <<The Python Editor>>: http://code.google.com/p/ulipad/
UliWeb <<simple web framework>>: http://uliwebproject.appspot.com
My Blog: http://hi.baidu.com/limodou

jun lin

unread,
Dec 30, 2009, 10:33:46 PM12/30/09
to pyth...@googlegroups.com
rst => latex => pdf的路子好像有点长。。
是否有谁知道我上面rst2pdf的路子哪里错了？

2009/12/31 limodou <lim...@gmail.com>

Zoom.Quiet

unread,
Dec 30, 2009, 10:34:37 PM12/30/09
to pyth...@googlegroups.com
2009/12/31 limodou <lim...@gmail.com>:
> 升级后我不是管理员了？
>
http://wiki.woodpecker.org.cn/moin/WoodpeckerAdminGroup
没有变...

--
http://zoomquiet.org 人生苦短? Pythonic!

金山常年招聘Py/C++人才! http://bit.ly/UoTV 简历直投俺就成;-)

Zoom.Quiet

unread,
Dec 30, 2009, 10:36:10 PM12/30/09
to pyth...@googlegroups.com
2009/12/31 jun lin <linjun...@gmail.com>:

> rst => latex => pdf的路子好像有点长。。
这是 标准路径，
自古就是如此的
> 是否有谁知道我上面rst2pdf的路子哪里错了？
你这个工具自个儿不识别 Sphinx 自个儿定的一些标签哪

--
http://zoomquiet.org 人生苦短? Pythonic!

limodou

unread,
Dec 30, 2009, 10:59:39 PM12/30/09
to pyth...@googlegroups.com
2009/12/31 Zoom.Quiet <zoom....@gmail.com>:

> 2009/12/31 limodou <lim...@gmail.com>:
>> 升级后我不是管理员了？
>>
> http://wiki.woodpecker.org.cn/moin/WoodpeckerAdminGroup
> 没有变...
>

但是我没有修改网页的权力了。

Reply all
Reply to author
Forward
0 new messages