Your SlideShare is downloading. ×
Sphinxはじめの一歩
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×

Saving this for later?

Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime - even offline.

Text the download link to your phone

Standard text messaging rates apply

Sphinxはじめの一歩

984
views

Published on


0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
984
On Slideshare
0
From Embeds
0
Number of Embeds
5
Actions
Shares
0
Downloads
5
Comments
0
Likes
1
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. 岡山Python勉強会
  • 2.  Georg Brandllによって作成されたドキュ メント作成ツール。  記述方法は、マークアップ言語の reStructuredTextで記述を行う。  多様な出力フォーマットを持ってる。 (HTMLやLaTeXなど)
  • 3.  復数の出力形式に対応しているのでいちい ち出力形式ごとに作る必要がない。  プレーンテキストで記述しているのでファ イルのバージョン管理が楽。(Gitなどで管 理しやすい)  Python,コマンドプロンプトとテキストエ ディタのみで作成可能(Excel方眼紙いらな い)
  • 4. Python勉強会なので、すでにPython はイン ストールされている前提で… easy_installの場合 $easy_install sphinx pipの場合 $pip install sphinx これだけ。
  • 5. ドキュメント作成準備としてプロジェクト を作成する。 コマンドプロンプトにて作成したいフォルダへ移動後、以 下のコマンドを実行します。 $sphinx-quickstart
  • 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](おすすめはy)
  • 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. よく使うであろう記述構文は、 • 表題 • インラインマークアップ • リスト • テーブル • コードブロック
  • 14. ============ はじめに作成する ============ インラインマークアップ ================= その1 -----**太字**
  • 15. **太字** *斜体* ``リテラル`` `リンク付きテキスト <http://python.org>`_
  • 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
  • 19. 他にも色々な構文があるので詳しくは 公式サイトを参考にして下さい。 公式サイト http://sphinx-users.jp/index.html
  • 20. 作成したフォルダ内にあるmake.bat(MakeFile)を 使ってコンパイルを行う。 $make html 構文等に間違いがなければbuildフォルダにhtml フォルダが作成され、その中にhtmlに変化された ファイルが入る。
  • 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でやるといいかも。(一元化できる) まずは使ってみて、運用を考えてはいかがでしょ うか?
  • 25. Sphinxの日本ユーザ会 http://sphinx-users.jp/index.html Sublime textでSphinxを使う。 http://bit.ly/1hFOPqL
  • 26. ご清聴ありがとうございました。