ReadtheDocs

ドキュメントを読むソフトウェアのドキュメントを記述するための非常に良い、といくつかのチュートリアルを書き、電子書籍などが挙げられます。あなたがシリーズを書きたい場合は、いくつかの1つのまたは2の記事のための本、より美しく、より多くのシステムの形で書かれたように、メモを取るか、ブログを書くことができます明確に書くことができるようにしますが、。
ドキュメントを読んで、あなたが使用する場合は、さまざまなバージョン管理システムから文書をインポートすることができ、オンラインドキュメントホストしているシステムでウェブフックを readthedocs後に、サイトへのビルドとアップロード自動的にすることができ、その後、非常に便利な、コードを毎回提出します。

電子書籍書かれた道を、既存の、いくつかのソリューションがあり、長所と短所も明らかです。

散文、不便インデックスとヒープ一緒に、ブログ。
GitHubのWikiの、知識の統合に適した、しかし、一般的なレイアウト、便利鑑賞。
GitBookは、スタイルが良い、遅いアクセス速度を見ていません。

比較すると、最後に、GitHubには、文書をホスティングドキュメントを生成するためにスフィンクスで、オーサリングツールのドキュメントとしてスフィンクス+ GitHubの+ ReadtheDocsをロックし、その後、ReadtheDocsにインポート。

スフィンクス

スフィンクスは、Pythonベースのドキュメント生成プロジェクトで、最初の公式文書が唯一のPythonを生成するために使用され、最適なツールで、より多くのよく知られたプロジェクトも、ドキュメントを生成するためにそれを使用し、さらに使用して本を書くためにそれを使用することができますreStructuredTextのドキュメント書き言葉として、だけでなく、私はマークダウンフォーマットをサポートする方法を紹介しますので、モジュールを介して他のフォーマットをサポートすることができます。

インストールスフィンクス：

pip install sphinx sphinx-autobuild sphinx_rtd_theme

コピー

このステップでは、ように、時間依存のpython、忍耐との多くをインストールします。..

初期化：

# 创建文档根目录
mkdir -p /root/work/scrapy-cookbook
cd scrapy-cookbook/
# 可以回车按默认配置来写
sphinx-quickstart

コピー

ここに私の塗りつぶしだ、他は基本的にデフォルト設定します：

> Separate source and build directories (y/n) [n]:y
> Project name: scrapy-cookbook
> Author name(s): Xiong Neng
> Project version []: 0.2
> Project release [1.0]: 0.2.2
> Project language [en]: zh_CN

コピー

ソフトウェアツリービューディレクトリツリー構造のインストール：

yum install tree

コピー

そして、実行tree -C .ビュースフィンクス構造が生成されます。

.
├── build
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── index.rst
    ├── _static
    └── _templates

コピー

次のように、ソースディレクトリ内の記事新しいhello.rstを追加します。

hello,world
=============

コピー

index.rst 次のように改正：

Contents:
.. toctree:: :maxdepth: 2 hello

コピー

テーマsphinx_rtd_themeを変更

ソース/ conf.pyを変更します。

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

コピー

試写

そして、より多くの実行ディレクトリmake html、入力したbuild/htmlディレクトリを開いているブラウザindex.html

画像

toctreeこの設定toctree python.rst、別のディレクトリにあるjava.rstノート、するために、例えば、マルチレベルのディレクトリをサポートしています。

Contents:

.. toctree::

   python/python swift/swift

コピー

なお、空白行の途中で

値下げの書き込みをサポートしています

recommonmark値下げをサポートするために、

pip install recommonmark

コピー

そして、conf.pyを変更します。

from recommonmark.parser import CommonMarkParser
source_parsers = { '.md': CommonMarkParser, } source_suffix = ['.rst', '.md']

コピー

AutoStructify

あなたは高度な機能を使用したい場合は、AutoStructify設定を追加することができますconf.pyに追加します。

# At top on conf.py (with other import statements)
import recommonmark
from recommonmark.transform import AutoStructify # At the bottom of conf.py def setup(app): app.add_config_value('recommonmark_config', { 'url_resolver': lambda url: github_doc_root + url, 'auto_toc_tree_section': 'Contents', }, True) app.add_transform(AutoStructify)

コピー

オンライン詳細な設定があります：https://github.com/rtfd/recommonmark/blob/master/docs/conf.py

ちょうどその修正hello.rstおなじみの賛成hello.md書き込みを：


## hello world

### test markdown

コピー

もう一度実行してmake html以前のように、結果を確認するために、後で。

GitHubのホスティング

一般的には、そのバージョン管理の両方の利点があり、自動的にreadthedocに公開することができ、それはあまりにも便利である、例えば上で自動的にビルドreadthedocにソースコードを公開するために上記のgithubのをホストし、プッシュとして文書のバージョン管理システムにあります。

GitHubのにscrapy-料理と呼ばれるリポジトリを作成し、ローカルの.gitignoreファイルに追加build/ディレクトリ、初期化gitの、後にコミット、リモートリポジトリを追加します。

具体的な手順は非常に簡単です、公式ドキュメントを参照してください。https://github.com/rtfd/readthedocs.org：

読むドキュメント上記でアカウントを登録します
着陸後、「インポート」をクリックしてください。
こうした「scrapy-料理」などの名前を入力し、HTTPSリンクの上GitHubの上にプロジェクトを追加し、タイプのGitリポジトリを選択するプロジェクトのドキュメント
その他のプロジェクトをクリックして「作成」を充填した後、彼らのニーズに応じて、自動的にGitHubの設定に行っていない、ウェブフックの後に無効にして作成します
限り、あなたは、このコードのリポジトリにプッシュするよう、文書上記readthedocが自動的に更新されますので、すべてが、解決しました。

注：読みの作成ドキュメントは、時間を投影し、言語選択「簡体字中国語」

あなたはreadthedocにログインすることができ、ビルドプロセス中にすべての問題は、任意のビューに詳細なログをクリックし、工事履歴を表示するためのプロジェクト「ビルド」のページを見つけました：

画像

自分自身についての記事内の私の以前のブログは、今の結果を見て、readthedocに移行したscrapy：

画像

PDFを生成します

私たちは、最初のTeXライブの古いバージョンなので、公式サイトの直接インストール版でのCentOSのyumリポジトリ7、TeXのライブをインストールする必要があります。

ではページ面公式のダウンロードパッケージがインストール-TL-unx.tar.gzを

あなたが最初の依存関係をインストールする場合：

yum install perl-Digest-MD5

コピー

その後、インストールを抽出します。

tar zxf install-tl-unx.tar.gz
cd install-tl-*
./install-tl  # install-tl-windows on Windows
[... messages omitted ...]
Enter command: i
[... when done, see below for post-install ...]

コピー

インストールの時間が長くなります、私はおそらく50分程度、ここでインストールしたい、しばらくお待ちください...

インストール設定PATHの後、中/etc/profileのバック追加：

export PATH=/usr/local/texlive/2016/bin/x86_64-linux:$PATH

コピー

あなた自身の正しいパスに上記のパスは、次に実行することを注意source /etc/profileします

あなたは中国のPDFを生成する場合、また、あなたは、東アジアの言語パックとフォントパッケージをインストールすることを確認する必要があります

yum -y install fontconfig ttmkfdir
# /usr/share目录就可以看到fonts和fontconfig目录
# 首先在/usr/share/fonts目录下新建一个目录chinese：
cd /usr/share/fonts
mkdir chinese
# 紧接着需要修改chinese目录的权限：
chmod -R 755 /usr/share/fonts/chinese
# 从C:/Windows/Fonts目录复制你想要的字体到chinese文件夹
# msyh.ttf msyhbd.ttf simhei.ttf simsun.ttc wqy-microhei.ttc YaHeiConsolas.ttf
ttmkfdir -e /usr/share/X11/fonts/encodings/encodings.dir
vi /etc/fonts/fonts.conf
<!-- Font directory list -->
<dir>/usr/share/fonts</dir> <dir>/usr/share/fonts/chinese</dir> fc-cache fc-list :zh

コピー

使用XeLaTeXはpdflatexをを交換する、我々は変更する必要がありますconf.py：

# 注：在生成html的时候这句话要注释
latex_engine = 'xelatex'

コピー

その後、実行します。

make clean
make latexpdf

コピー

終了後build/latex、あなたは、生成されたPDFファイルのディレクトリを見つけることができます。

ReadTheDocs可以自动生成中文PDF，但ReadTheDocs服务器里的TeXLive版本太老，导致只能使用pdflatex而不能使用xelatex编译，再加上服务器上中文字体的限制，所以生成的PDF效果较差，故不采用ReadTheDocs生成的PDF
本地安装TeXLive 2016，用xelatex编译，可生成更好效果的PDF，目前的策略是在本地生成PDF。

生成繁体PDF

先安装opencc

wget https://github.com/BYVoid/OpenCC/archive/master.zip unzip master.zip yum install -y cmake gcc gcc-c++ doxygen cd OpenCC-master make && make install ln -s /usr/lib/libopencc.so.2 /usr/lib64/libopencc.so.2

Copy

写一个shell脚本来转换源码：

#!/bin/bash
# 将某个文件夹所有文件简体转换成繁体字

curdir=`pwd`
file_dir=${curdir}/$1
for f in $(find $file_dir -type f); do
    #echo $f
    opencc -i "${f}" -o "${f}_"
    mv -f "${f}_" "${f}"
done

Copy

简体转繁体

./stot.sh scrapy-cookbook/source/

Copy

然后上面的生成PDF步骤不变。

FAQ

build的时候出现错误：! Package inputenc Error: Unicode char 我 (U+6211)

解决办法，在conf.py中添加:

latex_elements={# The paper size ('letterpaper' or 'a4paper').
'papersize':'a4paper',# The font size ('10pt', '11pt' or '12pt'). 'pointsize':'12pt','classoptions':',oneside','babel':'',#必須 'inputenc':'',#必須 'utf8extra':'',#必須 # Additional stuff for the LaTeX preamble. 'preamble': r""" \usepackage{xeCJK} \usepackage{indentfirst} \setlength{\parindent}{2em} \setCJKmainfont{WenQuanYi Micro Hei} \setCJKmonofont[Scale=0.9]{WenQuanYi Micro Hei Mono} \setCJKfamilyfont{song}{WenQuanYi Micro Hei} \setCJKfamilyfont{sf}{WenQuanYi Micro Hei} \XeTeXlinebreaklocale "zh" \XeTeXlinebreakskip = 0pt plus 1pt """}

Copy

WARNING: Pygments lexer name u’python run.py’ is not known

解决办法，写代码的时候别用’’’python run.py这样的格式，不支持

WARNING: nonlocal image URI found

解决办法，更改conf.py

import sphinx.environment
from docutils.utils import get_source_line def _warn_node(self, msg, node, **kwargs): if not msg.startswith('nonlocal image URI found:'): self._warnfunc(msg, '%s:%s' % get_source_line(node), **kwargs) sphinx.environment.BuildEnvironment.warn_node = _warn_node

Copy

生成的PDF文件中图片不能显示的问题

解决办法，因为文章里面引用的是外部图片链接，导致不能显示图片，将图片下载到source/images目录，然后改链接为相对路径。

如要居中显示图片，使用:

<center>![scrapy架构图](/images/scrapy.png)</center>

Copy

自动生成标题问题

修改conf.py将manual改成howto

latex_documents = [
    (master_doc, 'scrapy-cookbook.tex', u'scrapy-cookbook Documentation', u'Xiong Neng', 'howto'), ]

Copy

图片覆盖文字的问题

养成一个好习惯就是新增图片一定要空一行

one line

![scrapy架构图](/images/scrapy.png) two line

Copy

生成的pdf文件中，每个章节都多了一层编号

我猜测这个问题的原因是sphinx将rst转为LaTex文件，再转为PDF的。sphinx生成的LaTex文件中，使用了\Section标记段落，默认情况下\Section是自动编号的章节，而\Section*才是不带自动编号的。

为了解决这个问题，需要手工编辑sphinx生成的python3-cookbook.tex

cd build/latex/
vi scrapy-cookbook.tex

Copy

で\setcounter{tocdepth}{2}下の行を追加します。\setcounter{secnumdepth}{-2}

この行は、結果のPDFカタログが正しいと自動章番号なしでそうすることを、章番号カウンタを閉じました。ノート、スタッフの内側に手を触れないでください、空白行を削除すると動作しませんしてください。

次に、コマンドを実行します。

xelatex scrapy-cookbook.tex

コピー

この時点で生成されたPDFファイルは、通常の形式です。もし失敗した最初のパフォーマンスはもはや非常に奇妙なことを実行しないであろう。

具体的な原則について説明を参照してくださいhttp://liam0205.me/2015/04/10/how-to-list-unnumbered-section-in-the-table-of-contents/

最適化PDFの表示

このリファレンスhttps://github.com/yidao620c/python3-cookbook/issues/108

編集TeXファイル、プリアンブルの内容は次のとおりです。

前面省略...
\title{《Python Cookbook》第三版}
\date{Dec 09, 2017} \release{3.0.0} \author{熊能} \newcommand{\sphinxlogo}{\vbox{@@ \renewcommand{\releasename}{Release} \makeindex % 隐藏原目录名 \renewcommand{\contentsname}{} % 在 section 前插入分页 \usepackage{titlesec} \newcommand{\sectionbreak}{\clearpage} % 章节编号只编号到 subsection \newcommand\normalsecnumdepth{\setcounter{secnumdepth}{2@@ % 所有层次章节都不编号 \newcommand\specialsecnumdepth{\setcounter{secnumdepth}{-2@@ % toc 到 subsection \newcommand\normaltocdepth{ \setcounter{tocdepth}{2} \addtocontents{toc}{\setcounter{tocdepth}{2@@ } % toc 到 section \newcommand\specialtocdepth{ \setcounter{tocdepth}{1} \addtocontents{toc}{\setcounter{tocdepth}{1@@ } \begin{document} \maketitle \specialsecnumdepth \specialtocdepth \renewcommand{\contentsname}{} \section{目录} \vspace{-36pt} \sphinxtableofcontents \phantomsection\label{\detokenize{index::doc@@ \section{版权} \label{\detokenize{copyright::doc@@\label{\detokenize{copyright:copyright@@\label{\detokenize{copyright:python-cookbook-3rd-edition-documentation@@ \begin{DUlineblock}{0em} \item[] 书名： 《Python Cookbook》3rd Edition \item[] 作者： David Beazley, Brian K. Jones ...

コピー

\section{第一章：数据结构和算法}挿入する前に、\normaltocdepth

\section{附录A}挿入する前に、\specialtocdepth

また、各章の過剰内容と空間の次の行を削除するには、次のコマンドを実行します。

sed -i '/Contents:/,+1 d' python3-cookbook.tex

コピー

再び（最高執行2）を実行するコマンドを生成します。

xelatex python3-cookbook.tex

この記事はより転載：https://www.xncoding.com/

著者：for_billy
リンクします。https：//www.jianshu.com/p/8aae1c1453ae
出典：ジェーンの本が
著者によって著作権で保護されています。著者は認可商業転載してください接触、非商用の転載は、ソースを明記してください。

技術文書をホスティング使用ReadtheDocs

ReadtheDocs

スフィンクス

インストールスフィンクス：

初期化：

テーマsphinx_rtd_themeを変更

試写

値下げの書き込みをサポートしています

AutoStructify

GitHubのホスティング

PDFを生成します

生成繁体PDF

FAQ

おすすめ