Sphinx で手軽に作るドキュメント

5,674 views

Published on

SphinxCon 2015 の発表内容です。

Published in: Software
  • Be the first to comment

Sphinx で手軽に作るドキュメント

  1. 1. Sphinx-Users.JP 山田 剛 SphinxCon JP 2015
  2. 2. 自己紹介 山田 剛 Web広告配信会社のインフラエンジニア  最近の仕事  サーバの調達からサーバ構築、管理  インフラ系サーバ(DNS、MAIL、Hadoop等)の運用  コミュニティ  Python mini hack-a-thon  Sphinx-Users.JP 2 Twitter: usaturn
  3. 3. 今日お話しする事 既にSphinxを使い始めている方向けに、 日常のメモを取りながらドキュメント を育てる方法をご紹介します。
  4. 4. 今日お話ししない事 Sphinxの詳細な使い方 巨大な文書の作り方 複数人作業を主とした文書の作り方
  5. 5. アジェンダ 1. メモを取ろう 2. 再構成しよう 3. ドキュメントの例 4. この方法の感想と課題 5. まとめ
  6. 6. 1. メモを取ろう 2. 再構成しよう 3. ドキュメントの例 4. この方法の感想と課題 5. まとめ
  7. 7. メモを取ろう 例えば1人プロジェクトが終わったり、 引継ぎをしようとして 「一からドキュメントを書こう」 として途方にくれてしまう事はありま せんか?
  8. 8. メモを取ろう  とにかく普段からSphinxプロジェクトの 中にreSTで作成したメモを放り込んでい く  構成等細かい事は気にしない  メモを残す事が大事
  9. 9. メモを取ろう reSTにまだ慣れていなければこれだけでいい セクション 箇条書き toctree
  10. 10. 1. メモを取ろう 2. 再構成しよう 3. ドキュメントの例 4. この方法の感想と課題 5. まとめ
  11. 11. 再構成しよう ある程度関連ドキュメントが溜まって きたらまとめどき toctreeやindexを編集する 足りない部分を肉付けする 他のSphinxプロジェクトに分離する
  12. 12. 1. メモを取ろう 2. 再構成しよう 3. ドキュメントの例 4. この方法の感想と課題 5. まとめ
  13. 13. ドキュメントの例
  14. 14. 1. メモを取ろう 2. 再構成しよう 3. ドキュメントの例 4. この方法の感想と課題 5. まとめ
  15. 15. この方法の感想と課題 このやり方が良かったところ 人に見てもらいやすい  オレオレマークアップのテキストや Wordを開いて見るより見やすい。  まとまっているのでファイルサーバを 片っ端から漁るより探しやすい 他のSphinxドキュメントにくっつけ る事が容易い
  16. 16. この方法の感想と課題 課題 Sphinxを使ってくれない人と一緒に Sphinxドキュメントを作成する事が できない 他のツール(wikiやWord、オレオレ マークアップ)を利用している人がい たり使い分けを明確にできていない
  17. 17. 1. メモを取ろう 2. 再構成しよう 3. ドキュメントの例 4. この方法の感想と課題 5. まとめ
  18. 18. まとめ 1. 新しいやり方や、初めて知ったtips など片っ端からreSTでメモする 2. 初めに使う記法は「セクション」 「箇条書き」「toctree」だけでも 良い 3. ドキュメントが溜まってきたら再 編集したり分離したりする
  19. 19. Sphinxをはじめよう!
  20. 20. 以上 ご清聴ありがとうございました

×