スフィンクス自動化された文書

ディレクトリ

スフィンクス

スフィンクスは簡単に知的で美しいドキュメントの作成をするツールです。著者はBSDライセンスに基づいて、ゲオルク・ブランドルです。最初の書き込みPythonドキュメントとスフィンクスの出生時に、今、さまざまな言語のためのソフトウェア開発ドキュメントの生成をサポートしています。書き言葉としてスフィンクスreStructuredTextの使用は、あなたが使用することができ値下げ+ライブラリの拡張モードは、文書に書かれています。

公式サイト：httpsを：//www.sphinx.org.cn/

これは、次の優れた機能を備えています。

• 出力フォーマット：（WindowsのHTMLヘルプファイルを含む）HTML、ラテックス（PDFとして印刷することができます）、EPUB（人気の電子書籍フォーマット）、Texinfoの、マニュアルページ（マン・マニュアル）、プレーンテキスト（プレーンテキスト）。
• 幅広い相互参照：セマンティックタグと関数、クラス、参考文献、用語集と同様の自動リンク情報。
• 階層化アーキテクチャ：簡単にドキュメントツリー、自動的に同じレベルにリンクされ、上司と部下を定義します。
• 自動インデックス：一般的な指標だけでなく、言語固有のモジュールインデックス。
• コードはハイライト表示：蛍光ペンを自動的に強調表示Pygmentsを使用します。
• 拡張：自動テストコードの断片を、同様にPythonモジュール（APIドキュメントに）説明文字列を備えます。
• 豊富な拡張：ユーザーはそれらのほとんどはは、PyPIからインストールすることができ、第二のリポジトリに50の以上の拡張に貢献。

入門

• インストール：スフィンクスは、上記のpython2.4とを依存しています。

pip3 install -U sphinx

• ドキュメンテーションプロジェクトの作成：プロジェクトのdocサブディレクトリのルートディレクトリに作成し、文書作成命令を実行するには、設定時にいくつかの相互作用を入力する必要があります。

$ sphinx-quickstart 

mickeyfan$ sphinx-quickstart
欢迎使用 Sphinx 2.4.3 快速配置工具。

请输入接下来各项设置的值（如果方括号中指定了默认值，直接
按回车即可使用默认值）。

已选择根路径：.

布置用于保存 Sphinx 输出的构建目录，有两种选择。
一是在根路径下创建“_build”目录，二是在根路径下创建“source”
和“build”两个独立的目录。
> 独立的源文件和构建目录（y/n） [n]: y

项目名称会出现在文档的许多地方。
> 项目名称: 5G Provider
> 作者名称: fanguiju
> 项目发行版本 []: v1.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> 项目语种 [en]: zh_CN

创建文件 ./source/conf.py。
创建文件 ./source/index.rst。
创建文件 ./Makefile。
创建文件 ./make.bat。

完成：已创建初始目录结构。

你现在可以填写主文档文件 ./source/index.rst 并创建其他文档源文件了。 用 Makefile 构建文档，像这样：
 make builder
此处的“builder”是支持的构建器名，比如 html、latex 或 linkcheck。

• 設定：プロジェクトの後に作成された文書は、あなたはどのようなファイルやサブディレクトリを参照することができます：

  • Makefileは：使用してmakeコマンドを、命令が（EGを使用することができるsphinx-build出力文書を構築します）。
  • _build：これは、生成されたトリガに特定の出力ファイルを格納するために使用されるディレクトリです。
  • _static：すべてのソースコードに（例えば写真）を属していない、ここに保存されたファイルの一部である、我々は後にビルドディレクトリにそれらを一緒にリンクします。
  • conf.py：スフィンクスは、端末を行う含む店舗の設定値、に使用されるsphinx-quickstartこれらの値は、選択しました。
  • index.rst：ルートディレクトリのドキュメントプロジェクト。あなたが別のファイルに文書を分割した場合、ディレクトリは、これらの文書を接続します。

• 文書化：index.rstファイル内のメインタイトルの後に、を含むコンテンツのリストがあるtoctree文は、それはすべての文書がインデックスにリンクされている一緒にもたらすでしょう。例えば：

# 我们想将一个新文件添加到文档中，并打算将其命名为 example.rst。

Contents:

.. toctree::
   :maxdepth: 2

   example

注：以下の内容example.rst

This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.

Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length 
of the subtitle itself, just like titles.

Lists can be unnumbered like:

 * Item Foo
 * Item Bar

Or automatically numbered:

 #. Item 1
 #. Item 2

Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo`` 
gives you super user powers! 

• ドキュメントの生成：実行make運命を、そしてHTMLが出力形式として指定されました。それはJavaScriptとCSSファイルを含むすべての生成されたコンテンツを、含まれているため、出力は直接サイトとして使用することができます。

$ make html

docs run-test: commands[0] | sphinx-build -W -b html doc/source doc/build/html
正在运行 Sphinx v2.4.3
正在加载翻译 [zh_CN]... 完成
制作输出目录... 完成
构建 [mo]： 0 个 po 文件的目标文件已过期
构建 [html]： 1 个源文件的目标文件已过期
更新环境: [新配置] 已添加 1，0 已更改，0 已移除
阅读源... [100%] index

查找当前已过期的文件... 没有找到
pickling环境... 完成
检查一致性... 完成
准备文件... 完成
写入输出... [100%] index

generating indices...  genindex完成
writing additional pages...  search完成
复制静态文件... ... 完成
copying extra files... 完成
dumping search index in Chinese (code: zh)... 完成
dumping object inventory... 完成
构建 成功.

HTML 页面保存在 doc/build/html 目录。

• 静的なページを生成します：私たちは二つのファイルからHTMLを生成した後、前の操作を終了するように、我々は完全な静的ページのウェブサイトを持っています。htmlディレクトリにビルド/ index.htmlをファイルにアクセスするためにブラウザを使用して

• 画像やその他の静的ファイルを追加します：静的ファイルは、（あなたは文書のレイアウトを作成するときにスフィンクスは、ディレクトリを作成）_staticディレクトリを配置している限り、あなたは簡単にそれを参照することができます。。example.rst静的リストは次のとおりです。

.. image:: _static/system_activity.jpg

• 修正皮膚：デフォルトでは、オプションのスキンの多くを提供スフィンクス、我々は例えば、変更することで調整conf.pyことができます。

html_theme = "classic"

• sphinx_rtd_themeスキンを使用します：
  • インストール

pip3 install sphinx_rtd_theme

- 配置

# conf.py

html_theme = 'sphinx_rtd_theme'

- 重新构建

make html

reStructuredTextの構文

見出し、リスト、テキスト、ポイント

This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.

Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length 
of the subtitle itself, just like titles.

Lists can be unnumbered like:

 * Item Foo
 * Item Bar

Or automatically numbered:

 #. Item 1
 #. Item 2

Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo`` 
gives you super user powers!

テーブル

.. csv-table::
    :header:参数,类型,含义
    :widths:2,2,5

    test1,String,这里是测试的第一行
    test2,int,这里是测试的第二行

ブロック

.. code-block:: xml

    public void test(){
        throws new Exception("this is a test");
    }

他のモジュールファイルへの参照

.. toctree::
    :macdepth: 3

    module one
    module two

ジャンプをクリックします

调用 :ref:`点击这里跳转<file.key>`

静的な画像を参照

.. image:: _static/system_activity.jpg