Skip to content

编译问题

问题一：编译conf.py文件时，发生中文格式问题

参考：

解决UnicodeDecodeError: 'ascii' codec can't decode byte 0xe5 in position 108: ordinal not in range(128

Python3异常-AttributeError: module 'sys' has no attribute 'setdefaultencoding'

编译conf.py文件时，发生中文格式问题

Running Sphinx v1.7.9
WARNING: the config value 'epub_title' is set to a string with non-ASCII characters; this can lead to Unicode errors occurring. Please use Unicode strings, e.g. u'Content'.
WARNING: the config value 'project' is set to a string with non-ASCII characters; this can lead to Unicode errors occurring. Please use Unicode strings, e.g. u'Content'.
loading translations [en]... done
making output directory...

...
...
UnicodeDecodeError: 'ascii' codec can't decode byte 0xe5 in position 0: ordinal not in range(128)

Encoding error:
'ascii' codec can't decode byte 0xe5 in position 0: ordinal not in range(128)
The full traceback has been saved in /tmp/sphinx-err-VIWOpI.log, if you want to report the issue to the developers.

有两种解决方法：

第一种是针对python2，在conf.py中如下代码，将编码格式改为utf-8

import sys 
reload(sys) 
sys.setdefaultencoding('utf8')

第二种是修改readthedocs编译环境，在Admin->Advanced Settings->Python interpreter:

将选项修改成CPython 3.x

问题二：pdflatex编译出错

编译过程中运行pdflatex时出错:

pdflatex -interaction=nonstopmode /home/docs/checkouts/readthedocs.org/user_builds/zj-computer-foundation/checkouts/latest/docs/source/_build/latex/sphinx.tex

出错提示:

This is pdfTeX, Version 3.14159265-2.6-1.40.16 (TeX Live 2015/Debian) (preloaded format=pdflatex)
restricted \write18 enabled.
entering extended mode
(/home/docs/checkouts/readthedocs.org/user_builds/zj-computer-foundation/checko
uts/latest/docs/source/_build/latex/sphinx.tex
LaTeX2e <2016/02/01>
Babel <3.9q> and hyphenation patterns for 81 language(s) loaded.
...
...    
(/usr/share/texlive/texmf-dist/tex/generic/oberdiek/gettitlestring.sty))
(/usr/share/texlive/texmf-dist/tex/latex/psnfss/t1phv.fd)

! Package inputenc Error: Unicode char 计 (U+8BA1)
(inputenc)                not set up for use with LaTeX.

See the inputenc package documentation for explanation.
Type  H <return>  for immediate help.
...

l.74 \sphinxtableofcontents

解决：pdfTex是用于生成pdf文件的命令，在Admin->Advanced Settings中选择取消pdf生成选项

Create a PDF version of your documentation with each build.

问题三：/source/contents.rst not found

更新sphinx版本从v1.8.0到v2.2.1，在本地编译没有问题，在readthedocs上发生如下问题

/home/docs/checkouts/readthedocs.org/user_builds/zj-sphinx-github-readthedocs/envs/latest/lib/python3.7/site-packages/recommonmark/parser.py:65: UserWarning: Container node skipped: type=document
  warn("Container node skipped: type={0}".format(mdnode.t))

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/zj-sphinx-github-readthedocs/envs/latest/lib/python3.7/site-packages/sphinx/cmd/build.py", line 304, in build_main
    app.build(args.force_all, filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/zj-sphinx-github-readthedocs/envs/latest/lib/python3.7/site-packages/sphinx/application.py", line 341, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/zj-sphinx-github-readthedocs/envs/latest/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 347, in build_update
    len(to_build))
  File "/home/docs/checkouts/readthedocs.org/user_builds/zj-sphinx-github-readthedocs/envs/latest/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 360, in build
    updated_docnames = set(self.read())
  File "/home/docs/checkouts/readthedocs.org/user_builds/zj-sphinx-github-readthedocs/envs/latest/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 472, in read
    self.env.doc2path(self.config.master_doc))
sphinx.errors.SphinxError: master file /home/docs/checkouts/readthedocs.org/user_builds/zj-sphinx-github-readthedocs/checkouts/latest/docs/source/contents.rst not found

Sphinx error:
master file /home/docs/checkouts/readthedocs.org/user_builds/zj-sphinx-github-readthedocs/checkouts/latest/docs/source/contents.rst not found

参考Sphinx error: master file [..]/checkouts/latest/contents.rst not found #2569

在conf.py中添加

master_doc = 'index'

原因是readthedocs使用的sphinx版本较低，导致无法找到起始页