SphinxでLaTeXとPDFを生成する方法

1年半前に自宅でSphinxドキュメントジェネレーターを導入したとき、PDFを生成するタスクに直面しました。 ケースは非常に困難でした。 リソースに関する既製の「実行」指示はありませんでした。 試行錯誤を繰り返しました。 3日間の苦労の後、必要なデザインのPDFを生成することができました。

行って忘れた-それは同じように動作します。 フォントに問題が生じるまで。 彼らは再び苦しみ、再び決心しました。 しかし、注目すべきこと-それ以来、PDFを生成するための既製の指示はインターネット上に登場していません。 したがって、私は広がりました。 内部には、コメントとテンプレートファイル、ReTe for LaTeXの機能を備えたアルゴリズムがあります。これらは経験的に収集しています。



この記事は、すでにSphinxを使用しているが、LaTeXまたはPDFに問題がある人を対象としています。 Sphinxをドキュメントツールとしてのみ検討している場合、これらの形式でドキュメントを準備および送信する方法を提示すると役立ちます。

PDF生成が既に提供されているReadTheDocsが私たちに合わなかった理由をすぐに言わなければなりません。

1. ドキュメントは、内部ネットワークでホストする必要があります。
2. ドキュメント（フォルダー）の一部のみをPDFにアップロードできる必要があります。
3. 世代はLaTeXを通過する必要があります。LaTeXのテンプレートは、さまざまなタスクや企業スタイルに合わせて変更したかったのです。

なぜLaTeX

最も単純なPDFの場合、 rst2pdfで十分です 。 しかし、最も単純なPDFは私たちには適していません。なぜなら、美化して、様式化されたテンプレートを使用する必要があるからです。 したがって、中間形式としてLaTeXを使用します。

ページネーション、目次、タイポグラフィ、ワードラップ、脚注、表、相互参照、イラストなどに関する多くの問題を解決できます。 LaTeXのドキュメント構造は個別にスタイル設定でき、同じデータ構造を異なるデザインで異なるフォーマットで表示できます。 LaTeXスタイルによって駆動されます。



クライアント向けの出力ドキュメントを生成するには、様式化されたPDFが必要です：ユーザーの指示、レポート、商用オファー、簡単なプレゼンテーション。

さあ始めましょう

Andrei Bezrukov（ @aur ）に感謝します。AndreiBezrukovは、初期情報を収集し、基本的なことを確認しました。

1.準備する

PythonとSphinxはすでにサーバー上にあるはずです（Debianがあります）。ドキュメントはreStructuredTextで準備され、その生成はhtml形式で検証されています。

LaTeX用のパッケージを配置します。 例：

sudo apt-get install texmaker gummi texlive texlive-full texlive-latex-recommended latexdraw intltool-debian lacheck libgtksourceview2.0-0 libgtksourceview2.0-common lmodern luatex po-debconf tex-common texlive-binaries texlive-extra-utils texlive-latex-base texlive-latex-base-doc texlive-luatex texlive-xetex texlive-lang-cyrillic texlive-fonts-extra texlive-science texlive-latex-extra texlive-pstricks 

conf.pyのドキュメント構成で、 latex_documentsパラメーターを追加/コメント解除します。

 # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'yourdoc.tex', u'DocName', u'YourName', 'manual'), ] 

LaTeXのその他の基本設定は次のとおりです。ページサイズ、フォント、プリアンブルなど。

2. LaTeXの生成

コマンドを実行します：

 sphinx-build -b latex doc/source/ doc/latex/ 

ここで、 sourceはルートindex.rstファイルがあるフォルダーで、 latexは宛先フォルダーです。

すべてのドキュメントは、個々のファイルではなく、すぐに生成されます。 その結果、多くのファイルがlatexフォルダーのルートに表示されます。その中で、.texファイルはlatex形式のメインドキュメントファイルです。 latex_default.zipアーカイブのこの段階でのフォルダーの内容の例。

3.ラテックス（.texファイル）への変更

LaTeXの基本レイアウトを変更する必要があり、conf.pyの基本設定では不十分な場合、ドキュメントテンプレート自体、そのレイアウト、スタイルを変更します。

.texファイルにはプリアンブルがあり（\ begin {document}まで）、パッケージが接続され、変数が定義され、スタイルを記述できます。 ここで、必要な追加パッケージを接続します。

例





.texファイルには \ maketitleディレクティブが含まれており、ドキュメント名（\ title）、作成者（\ author）、およびテキストが書き込まれた日付（\ date）に関する情報を使用して標準のカバーページを作成します。

\ maketitleを独自のテンプレートに置き換えることができます。 \ maketitleを置き換えるメインページのテンプレートである、自分用の独立したファイルTitlePage.texを作成しました。 さまざまなドキュメントに対して、さまざまなデザインテンプレートを使用します。

例



.texファイルの最後に、何らかの補完テンプレートを追加することもできます。 そのため、ロゴと連絡先を挿入し、場合によっては広告のような外部PDFファイルを挿入します。


logo.pngロゴをlatexフォルダーにコピーします。 カバーページテンプレートで使用されます。

4.生成pdf

次のコマンドを使用して、PDFドキュメントの第1世代を実行します。

 pdflatex yourdoc.tex 

ファイルはlatexフォルダーに表示されます。

• .aux-相互参照情報
• .toc-目次ファイル
• .log-PDF生成ログ
• .pdf-PDFファイル。 しかし、まだ目次はありません

次のコマンドを使用して、目次を生成およびスタイルします。

 makeindex yourdoc.idx 

PDFの最終生成を繰り返し実行します。

 pdflatex yourdoc.tex 

最終的なPDFファイルは同じフォルダーに表示されます。 latex_modified.zipアーカイブのこの段階でのフォルダーの内容の例。

中間世代を行わない場合、出力は目次のないドキュメントになります。 ルートファイルの目次は、PDFブックの目次になります。 各ファイルの目次は、各章の目次になります。 すべての目次リンク、内部および外部のReSTリンクが正しく転送されます。

ReSTにエラーがある場合（画像がなく、構文が正しくないなど）、PDFを生成するときに、pdflatexコマンドもエラーを生成し、ユーザーアクションを待ちます（Enter-スキップして続行、H-自動的に修正、X-割り込み生成）。 この対話型コマンドを無効にするには、最初のエラーでプロセスを終了するパラメーターを指定してコマンドを呼び出す必要があります。

 pdflatex -halt-on-error yourdoc.tex 

LaTeX生成のReST要件

htmlバージョンの場合、これらの要件は重要ではなく、ドキュメントは引き続き生成されます。 しかし、LaTeXの場合、これは致命的です。 リストは経験的にコンパイルされます。

1. テキストで使用される画像が物理的に存在している必要があります。
2. デフォルトでは、箇条書きと番号付きリストの最大ネストは3です。それ以上ある場合、エラーが発生します（「LaTeXエラー：ネストが深すぎます」）。 この方法で解決され、検証されます。
3. リスト（ソースコード）：長い行にはハイフンを付けます。これは自動的には行われません。 そうでない場合、行はページの制限を超えて「カットオフ」されます。
4. どこかからテキストをコピーする場合、特殊文字があれば削除します（絵文字、html特殊文字）。
5. ReST構文エラーがないことをお勧めします。

また、画像、表、警告ブロックがある場合、ページが不適切に破損する場合があります。 次に、最初のファイルで、ラテックスの改ページを設定する必要があります。

 .. raw:: latex \newpage 

フォントの問題

問題が発生した場合、まずログを見てください-理由は異なる場合があります。 2つの状況がありました。 コメントに自分のものを追加します。

ある晴れた日、世代は機能しなくなりました。 サーバーの更新に関連付けられています。 ログを確認しました-スフィンクスは別のフォルダーでフォントを探し始めました。 サーバーの起動時に指定されたマウントフォントフォルダーを使用して決定しました。

別のケース。 LaTeXにはtfmフォントが必要です。 サーバーにフォントをインストールすると、自動的に生成されます。 何らかの理由で、これが常に機能するとは限りません。 このようなフォントの生成（ mktextfm <font name>コマンド）を手動で開始することでこれを解決しました。

無料でSMSなしでダウンロード

• rstのソースドキュメントの例： Generation_ Demo_PDF.tar.gz
• 変更前のLaTeXのサンプルドキュメント： latex_default.zip
• LaTeXおよび結果のPDFを変更した後のサンプルドキュメント： latex_modified.zip
• LaTeXテンプレートの例： www.latextemplates.com複雑なテンプレートのレイアウトは時間を浪費するものです。これに関する経験がない場合-限られた時間の条件では、誰かに注文する方が良いでしょう。

これにより、同様の問題を解決する際に数時間または数日節約できることを願っています。
PMでエラーを報告してください。