sphinx python 使用及国际化设置

sphinx python 使用及国际化设置

我写了一个sphinx Python 生成文档的demo,包括国际化。
git地址 https://github.com/tong822218/sphinxDemo

项目中的参数都是我已经配置好的，source/_static是项目的静态文件目录包括css，js，img
我在项目中引入了default.css 和 default.js两个文件作为默认的样式和脚本文件。
所以如果大家对编译之后的页面不满意，想要自己调一下的话在这两个文件中操作即可。

---

关于国际化,sphinx-intl只提供了文字的国际化，并没有图片引用的国际化(也可能是我没有找到解决方法，如果有大神知道，欢迎来赐教一番)。所以我在引入的default.js文件中对引用的图片进行了处理，通过判断url来判断应该引入哪种语言的图片所以图片只需要放入对应的文件夹就可以，必须保证各种语言的图片名称一致。

---

下面是具体的安装及使用方法.

由于国内pip下载资源过慢建议使用清华的镜像下载

例如：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx，
这样就会从清华这边的镜像去安装 sphinx 库, 亲测速度杠杠的.

• 安装sphinx

  pip install sphinx
  

• 使用Sphinx的向导quickstart自动生成默认的项目

  sphinx-quickstart
  

• 安装read the doc 主题

  pip install sphinx_rtd_theme  (如果不想用这个主题可以不安装 ,conf.py中将html_theme值改为alabaster即可)
  

• 安装中文分词搜索

  pip install jieba
  

• 安装国际化模块

  具体操作可以参考这个网站 :http://lijiancheng0614.github.io/2016/02/16/2016_02_16_Python_Sphinx/
  说的比较详细了我就不再赘述了,核心代码是:

  pip install sphinx-intl 
  

  除此之外还有一些对conf.py的配置,链接中都有提到(demo中已经配置好)

• 进入到项目根目录运行命令:

  make gettext && sphinx-intl update -p build/gettext -l zh_CN -l zh_TW -l en &&
  sphinx-build -D language=zh_CN -b html ./source build/html-zh &&
  sphinx-build -D language=zh_TW -b html ./source ./build/html-tw &&
  sphinx-build -D language=en -b html ./source ./build/html-en    
  

  执行上面命令在 source/locale/ 下会生成对应的三种语言的文件,打开对应的.po文件填入对应的国际化即可 如:

  msgid “常见问题”
  msgstr “FAQ”
  (友情小提示:如果FAQ这里写的是1. FAQ 那么国际化翻译可能会失败,主要是 “1. ” 后面的空格造成的,删掉空格即可,可能是编码的问题.)

• 填写完国际化后然后再运行上面的命令即可,编译后的文件都在build下.

---

这个小demo除了这些安装 ,命令,最麻烦的地方可能是conf.py文件的配置了,我遇到的比较费时的是下面这个问题

官方文档中提到的一些配置我在实际操作中发现有些不起作用 比如 这段:

Add any paths that contain custom static files (such as style sheets) here,
relative to this directory. They are copied after the builtin static files,
so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

说是在_static中放一个default.css文件就会覆盖掉原始的样式,但我发现,如果我们引用的不是默认主题,那么页面中是不会引用defalut.css的 所以不起作用,可以用下面的配置替换这个方法

def setup(app):
    app.add_stylesheet("default.css") # also can be a full URL
    app.add_javascript("default.js")

在conf.py中写入这段代码,意思是将我们的default.css 和defalut.js 写入编译好的html页面中

不要用editplus,这是我踩的一个坑,因为存在一个编码问题,python编译时候会报错,
玩过python的应该都能解决,解决不了那就换一个编辑器吧 比如 vscode