
3. ハンズオン：勉強会レポートを作成しよう

では、実際にドキュメントを書いてみましょう。

今回の勉強会のレポートを作っていきます。

文章はみなさんで好きなように書いていただいて問題ありません。

3.1. 書く項目を決めます

こんなことを書きましょうか

  • 勉強会のタイトル
  • 開催情報
  • 勉強会の内容
  • 資料

3.2. Sphinxプロジェクトを作りましょう

まずは、好きなディレクトリに移動して、sphinx-quickstartを実行します。

以下では report というドキュメント名を指定して実行しています。

sphinx-quickstart report

Welcome to the Sphinx 1.2 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: report

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]:

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 [_]:

The project name will occur in several places in the built documentation.
> Project name: Sphinx勉強会レポート
> Author name(s): 五十嵐大輔

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]:

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]:

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]:

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n]:

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]:
> doctest: automatically test code snippets in doctest blocks (y/N) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
> coverage: checks for documentation coverage (y/N) [n]:
> pngmath: include math, rendered as PNG images (y/N) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/N) [n]:
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:
> viewcode: include links to the source code of documented Python objects (y/N) [n]:

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]:
)
> Create Windows command file? (Y/n) [y]:

Creating file report/conf.py.
Creating file report/index.rst.
Creating file report/Makefile.
Creating file report/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file report/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

今回は、index.rstの中身は必要ないので、一旦全て削除します。

3.3. まずはタイトル

まずは勉強会のタイトルを書きます。

============
Sphinx勉強会
============

上のように 文字の上下に同じ長さの記号 を書くと、セクション になります。

文字列よりも短いとだめです。長い分には問題無いです。

文字の下に文字列と同じ長さの記号を書いても同じです。

１つのファイルの中で一番最初にでてくるセクションがページのタイトルになります。

index.rstを編集したら保存して、make htmlでビルドして確認してみましょう。

make html

sphinx-build -b html -d _build/doctrees   . _build/html
Making output directory...
Running Sphinx v1.2
loading pickled environment... not yet created
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
writing additional files... genindex search
copying static files... done
copying extra files... dumping search index... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in _build/html.

ビルドが完了したら _build/html/index.html を開きます。

$ open _build/html/index.html

以下のようになっていれば成功です。

_images/03_01.png

3.4. 続いて、各セクションを作成します。

============
Sphinx勉強会
============

開催情報
========

勉強会の内容
============

資料
====

各セクションの文字列の下に、-や=で線を引きます。これでセクションを作ることができます。

セクションは全部で６レベル分作ることができ、 出現した順番にレベル分けされます。

セクション名に使用できる記号はたくさんありますが、見やすさから:

= - ` : . ' " ~ ^ _ * + #

これらが推奨されているようです。

3.5. 参加者と日時

次に、開催情報に参加者と日時を箇条書きを使って追加しましょう。

開催情報
========
* 日時： 2013/12/21 13:00-17:00
* 場所： CoCoDe
* 参加者： planset, ...

* + -とスペースを１つ入れてから文章を書くとリストになります。

ビルドすると、<ul><li>に変換されます。

番号付きリストも使うことができます。

1. 項目1
2. 項目2
3. 項目3

上のように書くと、<ol><li>に変換されます。

番号付きリストは1.,2.,3.以外にも、(1),(2),(3)...や1),2),3)やA.,B.,C.でも書けます。

また、#.を使うことで自動で番号をふることもできます。

3.6. 勉強会の内容　段落、引用文

長い文章を書いている場合、段落として区切りたいときがくるはずです。ええきっと。

その場合には、空行を１つ入れて下さい。それだけで段落となります。

勉強会の内容
============
Sphinxの勉強会に参加してきました。

勉強会では、勉強会のレポートを書きながらSphinxについて学びました。

それはそうと講師の方がいけめｎうぇぎぃふろじｔｐｈこｌｙ；「

きっとレポートを書いていると、何かの資料を引用したくなります。

その場合には、行頭にひとつ以上のスペースを入れて文章を書くことで 引用文として<blockquote>に変換されます。

勉強会の内容
============
Sphinxの勉強会に参加してきました。

Sphinxとは次のようなツールです。

    Spihnxは、reStructuredText記法で書かれたテキストファイルをHTML、PDFやepubなどに変換するためのツールです。

    Pythonの公式ドキュメントはSphinxを使って書かれています。
    また、Python以外の多くのプロジェクトでもSphinxが利用されています。

勉強会では、勉強会のレポートを書きながらSphinxについて学びました。

行頭にいれたスペースが同じ数であれば、同じ引用の行として解釈されます。

3.7. リスト、サブリスト

先ほど箇条書きを書きましたが、サブリストもよく書きたくなります。

勉強会の内容に以下を追加しましょう。

sphinxを利用するために必要なこと

* テキストエディタ
* Sphinxの環境

  * python
  * (pip)
  * (virtualenv)
  * sphinx

* コマンドラインツールへの多少の慣れ

サブリストを書くときは、１行開けて書きます。

次に、トップレベルのリストの文章を書いているところを先頭として、 行頭にスペースを入れてリストを書いていきます。

3.8. 強調

ここが重要だ！ という文章は強調したいと思います。

強調を行うには、以下のように書いていきます。

種類 使用例 書き方 HTMLタグ
強調 文字列 *で囲む <em>
強い強調 文字列 **で囲む <strong>

先ほどのリストを強調してみます。

sphinxを利用するために必要なこと

* テキスト*エディタ*
* *Sphinx* の環境

  * *python*
  * (pip)
  * (virtualenv)
  * **sphinx**

* コマンドラインツールへの多少の慣れ

前後に文字が続く場合には、*の前または後ろにスペースを入れる必要があります。

3.9. 資料　リンク

文章を書いていると、外部へのリンクを作りたい場合があります。

次のように記述するとリンクを書くことができます。

資料
====

* http://sphinx-doc.org/
* `github <https://github.com>`_
* Sphinx-users.jp_

.. _Sphinx-users.jp: http://sphinx-users.jp/
  1. 普通にURLを書くと自動でリンクになる。
  2. 文字列 または スペースを 含む文字列 と書いておいて、 あとから .. _`スペースを 含む文字列`: URL とするとリンクになる。
  3. 文字列 とするとリンクになる。

3.10. ひとくぎり

まずはここまでの内容を使って、ドキュメントを作成してみてください。

作成が終わったら、make htmlです！








3.11. 複数のファイルを扱う。

いまindex.rstに作っていってもらいましたが、これが複数になってくると、 ファイルを分けて書きたくなります。

次はファイルを分けて管理してみましょう。

次のようなファイル構成を考えます。:

sample/
 |- index.rst
 |- report/
     |- 20131221_study_sphinx.rst
     |- 20131222_study_sphinx2.rst
     |- ・
     |- ・

この場合どうやってsphinxでビルドするか実際に操作してみましょう。

3.12. ファイルをリネームする。

まず、今までのindex.rstをリネームして、20131221_study_sphinx.rstにします。 もっと短い名前でもよいです。

ついでにそのファイルをコピーして、20131222_study_sphinx2.rstも作りましょう。

3.13. ディレクトリを作成する。

reportディレクトリを作りって先ほどの２つのファイルを入れます。

mkdir report
mv 2013* report/

3.14. index.rstを作成

次のようなindex.rstを作りましょう。

サンプルドキュメント
====================

Contents:

.. toctree::
    :maxdepth: 2
    :numbered:
    :glob:

    report/*


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

3.15. できたらビルドです

make html
open _build/html/index.html

文章の階層構造がtoctreeディレクティブにより解析されて、 きれいな目次ができます。

これで、ファイルが増えても大丈夫です。

また、大きな文書を書く場合でも章ごとにファイルを分けておいて、 変換時に１つの文書にすることもできます。

Read the Docs v: latest
Versions
latest
Downloads
HTML
Epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.
http://planset-study-sphinx.readthedocs.io/ja/latest/03.html
planset-study-sphinx.readthedocs.io
crawl=CC-MAIN-2017-26
33147
application/http; msgtype=response
sha1:M43IVJM7CBZG6GTOUZWXC2MC3FMTAL2N
<urn:uuid:da95a53d-145c-44c3-842e-58c4cfac6366>
2017-06-28T15:38:44Z
162.242.198.235
text/html
sha1:JIHMZKHEWLUHY42ATBEJAO5IXLMKE55W
<urn:uuid:f1553b1f-e2ac-4152-9601-9e5d9b217ba2>
http://planset-study-sphinx.readthedocs.io/ja/latest/03.html
response
<urn:uuid:e5f8a11d-c4a6-4c3f-ae88-a71a786ae49e>
robots: classic
hostname: ip-10-228-96-185.ec2.internal
software: Nutch 1.6 (CC)
isPartOf: CC-MAIN-2017-26
operator: Common Crawl Admin
description: Wide crawl of the web for June 2017
publisher: Common Crawl
format: WARC File Format 1.0
conformsTo: http://bibnum.bnf.fr/WARC/WARC_ISO_28500_version1_latestdraft.pdf