![Sphinx-quickstart実行時に設定を確認してく
るので順番に設定を行う。
ドキュメントのルートパス設定
Enter the root path for documentation.
>Root path for the documentation [.]:[enter]
出力先ディレクトリ設定を_buildにするかsource/buildフォルダに分離する
か設定
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/N) [n]:[enter](おすすめはｙ)](https://image.slidesharecdn.com/sphinx-131225061120-phpapp02/85/Sphinx-6-320.jpg)
![カスタムHTMLテンプレート(templates)と静的処理用(static)フォルダの接頭
語設定
Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other
static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:[enter]
プロジェクト名と作成者名の設定
The project name will occur in several places in the built documentation.
>Project name: project_name
> Author name(s): Hoge](https://image.slidesharecdn.com/sphinx-131225061120-phpapp02/85/Sphinx-7-320.jpg)
![プロジェクトのバージョン指定(プロジェクトのバージョンとリリースを
分離するかを指定)
Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1. If you don't need this dual structure,
just set both to the same value.
> Project version:1.0.0
> Project release [1.0.0]:[enter]
ファイルの拡張子の設定
The file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.
> Source file suffix [.rst]:[enter]](https://image.slidesharecdn.com/sphinx-131225061120-phpapp02/85/Sphinx-8-320.jpg)
![ルートノードの設定(ドキュメントのルートファイルを何にするか指定)
One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:[enter]
Epub形式の出力に対応するか
Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n] :[enter]](https://image.slidesharecdn.com/sphinx-131225061120-phpapp02/85/Sphinx-9-320.jpg)
![拡張機能を指定する場合に設定。(あとから追加可能)
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]:[enter]
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:[enter]
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:[enter]
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:[enter]
> coverage: checks for documentation coverage (y/N) [n]:[enter]
> pngmath: include math, rendered as PNG images (y/N) [n]:[enter]
> mathjax: include math, rendered in the browser by MathJax (y/N) [n]:[enter]
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:[enter]
> viewcode: include links to the source code of documented Python objects (y/N)
[n]:[enter]](https://image.slidesharecdn.com/sphinx-131225061120-phpapp02/85/Sphinx-10-320.jpg)
![ドキュメント生成用make file(make.bat)を作成するかを設定
A Makefile and a Windows command file can be generated for you so
that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (Y/n) [y]:[enter]
> Create Windows command file? (Y/n) [y]:[enter]
クロスコンパイルを検討するのなら両方作成していてもいいと思う。
ドキュメントの環境をビルドごとに綺麗にして、デプロイしたい場合には、
バッチ等でビルドファイル削除後、ビルドするバッチを作っておくと便利。](https://image.slidesharecdn.com/sphinx-131225061120-phpapp02/85/Sphinx-11-320.jpg)
More Related Content
What's hot (20)
Viewers also liked (14)
Similar to 厂辫丑颈苍虫はじめの一歩 (20)
厂辫丑颈苍虫はじめの一歩
- 1. 冈山笔测迟丑辞苍勉强会
- 2. ? Georg Brandllによって作成されたドキュ メント作成ツール。 ? 記述方法は、マークアップ言語の reStructuredTextで記述を行う。 ? 多様な出力フォーマットを持ってる。 (HTMLやLaTeXなど)
- 3. ? 復数の出力形式に対応しているのでいちい ち出力形式ごとに作る必要がない。 ? プレーンテキストで記述しているのでファ イルのバージョン管理が楽。(Gitなどで管 理しやすい) ? Python,コマンドプロンプトとテキストエ ディタのみで作成可能(Excel方眼紙いらな い)
- 4. Python勉強会なので、すでにPython はイン ストールされている前提で… easy_installの場合 $easy_install sphinx pipの場合 $pip install sphinx これだけ。
- 6. Sphinx-quickstart実行時に設定を確認してく るので順番に設定を行う。 ドキュメントのルートパス設定 Enter the root path for documentation. >Root path for the documentation [.]:[enter] 出力先ディレクトリ設定を_buildにするかsource/buildフォルダに分離する か設定 You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/N) [n]:[enter](おすすめはｙ)
- 7. カスタムHTMLテンプレート(templates)と静的処理用(static)フォルダの接頭 語設定 Inside the root directory, two more directories will be created; "_templates" for custom HTML templates and "_static" for custom stylesheets and other static files. You can enter another prefix (such as ".") to replace the underscore. > Name prefix for templates and static dir [_]:[enter] プロジェクト名と作成者名の設定 The project name will occur in several places in the built documentation. >Project name: project_name > Author name(s): Hoge
- 8. プロジェクトのバージョン指定(プロジェクトのバージョンとリリースを 分離するかを指定) Sphinx has the notion of a "version" and a "release" for the software. Each version can have multiple releases. For example, for Python the version is something like 2.5 or 3.0, while the release is something like 2.5.1 or 3.0a1. If you don't need this dual structure, just set both to the same value. > Project version:1.0.0 > Project release [1.0.0]:[enter] ファイルの拡張子の設定 The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. > Source file suffix [.rst]:[enter]
- 9. ルートノードの設定(ドキュメントのルートファイルを何にするか指定) One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. > Name of your master document (without suffix) [index]:[enter] Epub形式の出力に対応するか Sphinx can also add configuration for epub output: > Do you want to use the epub builder (y/N) [n] :[enter]
- 10. 拡張機能を指定する場合に設定。(あとから追加可能) Please indicate if you want to use one of the following Sphinx extensions: > autodoc: automatically insert docstrings from modules (y/N) [n]:[enter] > doctest: automatically test code snippets in doctest blocks (y/N) [n]:[enter] > intersphinx: link between Sphinx documentation of different projects (y/N) [n]:[enter] > todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:[enter] > coverage: checks for documentation coverage (y/N) [n]:[enter] > pngmath: include math, rendered as PNG images (y/N) [n]:[enter] > mathjax: include math, rendered in the browser by MathJax (y/N) [n]:[enter] > ifconfig: conditional inclusion of content based on config values (y/N) [n]:[enter] > viewcode: include links to the source code of documented Python objects (y/N) [n]:[enter]
- 11. ドキュメント生成用make file(make.bat)を作成するかを設定 A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. > Create Makefile? (Y/n) [y]:[enter] > Create Windows command file? (Y/n) [y]:[enter] クロスコンパイルを検討するのなら両方作成していてもいいと思う。 ドキュメントの環境をビルドごとに綺麗にして、デプロイしたい場合には、 バッチ等でビルドファイル削除後、ビルドするバッチを作っておくと便利。
- 12. フォルダ構成 ./ ├─build(ビルド結果の保存先) ├─source │ ├─_static(静的処理用フォルダ) │ ├─_templates(テンプレートフォルダ) │ ├─conf.py(内部設定用ファイル) │ └─index.rst(indexファイル) ├─makefile(ドキュメント用スクリプト) └─make.bat (ドキュメント用バッチ) 上記の構成で作成されるのでとりあえず sourceフォルダ内に****.rstを作成する。
- 13. よく使うであろう記述構文は、 ? 表題 ? インラインマークアップ ? リスト ? テーブル ? コードブロック
- 16. *宇都宮市 * 那須塩原市 * 真岡市 1. まさし 2. みんみん #. 夢餃子(#を使うと、自動で数字が割り当てられます) 餃子 宇都宮の名物として有名。餃子の像もある。静岡の浜松がライバル。 ジャズ 宇都宮はジャズの町としても売り出し中。 楽器メーカーを多数抱える 静岡の 浜松がライバル 焼きそば 知る人ぞ知る宇都宮の名物。専門店多数。なぜかビニール袋で持ち帰る。
- 17. +----------------------------+ |栃木県内の勉強会 | +=====+=========+ |宇都宮 |集合知勉強会 | + +-----------------+ | |Objective-C | +---------+-----------------+ |西那須野|とちぎRuby | +-----------+---------------+
- 18. .. code-block:: python import os class ClassName(object): """docstring for ClassName""" def __init__(self, arg): super(ClassName, self).__init__() self.arg = arg
- 21. ? 事前にindex.rstに作成したドキュメントファイル を入れておくと、自動的に目次(見出し)が作成さ れる。 ? テーマのテンプレートを設定したい場合には、 conf.pyの設定を変更すると見た目を変えること が可能。 ? Block-dialog等も書いたり、docx(word)出力が可 能だが別途プラグインが必要。(2.7以外でも動く のか？)
- 22. ? なるべくエディタのフォントは等幅の物を使い 作成する。(見出しのエラーを見落とすことが 多々あるので…) ? 作成したファイルは、UTF-8で保存(エディタに よっては、変換をしくじる可能性があるため) ? 日本語フォルダは、ダメ(変換(ry) ? 文章内のtab/空行で見え方が変わるので注意が必 要。
- 23. ? sublime text使うとhtml変換を自動化できるので 効率化できる。(以前、ブログで書いた) ? ファイル自体はpythonファイルとテキストファ イルなのでGitなどで管理すると履歴管理もでき る。 ? Docx builder を使うとwordファイルへの出力 もできる。(Excelは無理)
- 24. ? reStracturedTextは、若干クセがあるが慣れれば それっぽいドキュメントが書ける。 ? Sublime textすげえ便利。(Customizeすると) ? ドキュメントのバージョン管理することを考え るとGitでやるといいかも。(一元化できる) まずは使ってみて、運用を考えてはいかがでしょ うか?
- 26. ご清聴ありがとうございました。