ReadtheDocs管理ドキュメントの使用

Read the Docsはオンラインドキュメント管理サービスで、さまざまなバージョンの制御システムからドキュメントをインポートすることができます.webhooksを使用すると、コードをコミットするたびにreadthedocsサイトに自動的に構築され、アップロードすることができます.非常に便利です.
一般的に、これはソフトウェアドキュメントを書くことや、チュートリアル、電子書籍を書くことに適しています.いくつかの1、2つの文章に対してはっきり書くことができるのはメモを取ったり、ブログを書いたりすることができますが、シリーズを書くなら、本の形式を書くほうがいいです.もっと美しくて、もっと系統的です.
既存の電子書籍を書く方法には、以下のいくつかの解決策があり、優劣も明らかです.

ブログを書いて、散文と一緒に積み上げて、インデックスが不便です.

GitHub Wikiは、知識の整理に適していますが、レイアウトは一般的で、表示しにくいです.

GitBook、スタイルが悪く、アクセス速度が遅い.

最後にSphinx+GitHub+ReadtheDocsをドキュメント作成ツールとしてロックし、Sphinxでドキュメントを生成し、GitHubでドキュメントを管理し、ReadtheDocsにインポートします.
Sphinx
SphinxはPythonベースのドキュメント生成プロジェクトで、最初はPython公式ドキュメントを生成するために使用されただけで、ツールの完備に伴い、ますます多くの有名なプロジェクトも彼を使ってドキュメントを生成し、彼を使って本を書くことができ、reStructuredTextをドキュメント作成言語として採用したが、モジュールを通じて他のフォーマットをサポートすることもできる.あとでMarkDownフォーマットをサポートする方法を紹介します.
Sphinxのインストール:

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
インストールソフトウェアtreeディレクトリツリー構造を表示するには、次の手順に従います.

yum install tree

次に、tree -C .を実行して、生成されたsphinx構造を表示します.

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

記事を追加し、sourceディレクトリの下にhello.rstを新規作成します.内容は次のとおりです.

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

index.rstは以下のように修正された.

Contents:
.. toctree::
   :maxdepth: 2

   hello

トピックsphinx_の変更rtd_theme
source/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を開く
img
toctreeは、python.rst、java.rstを別のディレクトリにメモするなど、マルチレベルディレクトリをサポートします.toctreeは、次のように設定します.

Contents:

.. toctree::

   python/python
   swift/swift

真ん中の空行に注意
markdownの作成をサポート
recommonmarkでmarkdownをサポート

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ホスティング
一般的な方法は、githubなどのバージョン制御システムにドキュメントを管理し、pushソースコードを自動的に構築してreadthedocに公開することです.これにより、バージョン制御のメリットもあれば、readthedocに自動的に公開することができ、本当に便利です.
GitHubでscrapy-cookbookという倉庫名を作成し、ローカル.gitignoreファイルにbuild/ディレクトリを追加し、git,commitを初期化した後、リモート倉庫を追加します.
具体的な手順は簡単です.公式ドキュメントを参照してください.https://github.com/rtfd/readthedocs.org:

Read the Docsにアカウント

を登録

ログイン後「Import」をクリック.

この文書項目に「scrapy-cook book」などの名前を記入し、GitHub上の工事HTTPSリンクを追加し、倉庫タイプをGit

に選択します.

他の項目は自分の必要に応じて記入して「Create」をクリックし、作成後に自動的にWebhooksをアクティブにし、GitHub設定

に行く必要はありません.

すべてが終わって、それからあなたがこの倉庫のpushコードに行く限り、readthedocの上のドキュメントは自動的に更新されます.

注意:read the docsプロジェクトの作成時に言語選択「Simplified Chinese」
構築中に問題が発生した場合は、readthedocにログインしてプロジェクト内の「構築」ページにアクセスして構築履歴を表示し、詳細ログを表示するには、次のいずれかをクリックします.
img
以前のブログのscrapyに関する記事をreadthedocに移行しましたが、効果を見てみましょう.
img
PDFの生成
まずTeX Liveをインストールします.CentOS 7のyumライブラリのTeX Liveバージョンは古いので、公式サイトのバージョンを直接インストールします.
公式サイトページでインストールパッケージinstall-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

/usr/share/fonts
/usr/share/fonts/chinese

fc-cache
fc-list :zh

pdflatexの代わりにXeLaTeXを使用するには、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

ソースコードを変換する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

簡体字から繁体字へ

./stot.sh scrapy-cookbook/source/

その後、上記の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
"""}

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

生成されたPDFファイルに画像が表示されない問題
解決策は、文章の中で外部のピクチャリンクを参照しているため、ピクチャを表示できないため、ピクチャをsource/imagesディレクトリにダウンロードし、リンクを相対パスに変更します.
画像を中央に表示するには:

![scrapy   ](/images/scrapy.png)

タイトル問題の自動生成
修正conf.py manualをhowtoに変更

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

画像が文字を上書きする問題
新しい画像は必ず1行空けるという習慣を身につける.

one line

![scrapy   ](/images/scrapy.png)

two line

生成されたpdfファイルには、各章に番号が1つ追加されています.
この問題の原因はsphinxがrstをLaTexファイルに変換し、PDFに変換したからだと思います.sphinxで生成されたLaTexファイルでは、Sectionタグ段落が使用されています.デフォルトでは、Sectionは自動番号の章ですが、Section*は自動番号を付けません.
この問題を解決するには、sphinxで生成されたpython 3-cookbook.texを手動で編集する必要があります.

cd build/latex/
vi scrapy-cookbook.tex

\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{  }

ewcommand{\sphinxlogo}{\vbox{}}
\renewcommand{\releasename}{Release}
\makeindex

%       
\renewcommand{\contentsname}{}

%   section      
\usepackage{titlesec}

ewcommand{\sectionbreak}{\clearpage}

%          subsection

ewcommand
ormalsecnumdepth{\setcounter{secnumdepth}{2}}

%           

ewcommand\specialsecnumdepth{\setcounter{secnumdepth}{-2}}  

% toc   subsection

ewcommand
ormaltocdepth{
    \setcounter{tocdepth}{2}
    \addtocontents{toc}{\setcounter{tocdepth}{2}}
}

% toc   section

ewcommand\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{ ： }の前に挿入

ormaltocdepth

\section{ A}の前に挿入

\specialtocdepth

さらに、次のコマンドを実行して、各章の余分なContentsと次の行のスペースを削除します.

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

生成コマンドを再度実行します(2回実行することが望ましい):

xelatex python3-cookbook.tex