Linux カーネルでの Sphinx 利用法を見てみよう - Hack like a rolling stone
年末カウントダウン Sphinx 連載、第3弾です。 一切下準備をせずに連載を始めたので、早くも息切れをしています。 だれかと約束をしたわけでもないのに急にアドベントカレンダー的なものを始めるのは、なんだか死に急いでいる気がしてきました。 今回は、今年から Sphinx の利用者に加わったある大型プロジェクトについて紹介しましょう。 そのプロジェクトとは、世界最大級の OSS のひとつである Linux カーネルです。 現在の Linux カーネルドキュメント 今年開催された LinuxCon Japan 2016 で Linux カーネルのドキュメントに Sphinx を使うという発表がありました。 Linus Torvalds氏が登壇、「約10週間のリリースサイクルは続く」 - クラウド Watch それから約 5ヶ月。現在はどうなっているのか見てみましょう。 Linux カーネルのド
Sphinxを便利にして、みんなに使ってもらいたい - Qiita
Sphinxは非常に素晴らしいドキュメント生成ツールです。 この素晴らしいツールを社内で流行らせようと頑張ったのですが、誰も使ってくれません。 みんながどんなタイミングで、Sphinxを諦めてしまうのか振り返ってみました。 reStructuredTextがわからないし、覚えたくもない デフォルトのテーマが見にくいからやめる sphinx-quickstartの設問が多すぎて途中でやめる ドキュメント作成のたびにconf.pyを編集するのが面倒なので使わなくなる ドキュメント確認のたびにmake htmlが面倒なので使わなくなる 最近はJupyterでドキュメント書くので・・・ こんなところでしょうか。 たぶん、Sphinxがいまいち流行らないのも、ここら辺が理由が大きいんじゃないかと思います。 Markdownを使う 残念ながらマークアップ言語の主流はreStructuredTextでは
graphiteの時系列データをpandasとscikit-learnで予測して月次レポート化する仕組み
こんにちはCTOの馬場です。 弊社では業種柄、サーバごとのCPU利用率などたくさんの時系列メトリックデータを持っています。 以前はこの収集・閲覧にcactiを利用していましたが、最近はgrafana + graphiteを利用しています。 (ちなみにこれらは全て自社製OSS監視エージェントのhappo経由で収集されます) 今回はこのデータの活用例として弊社で実装している解析・レポーティングについて簡単に紹介します。 できること 全体としては月次レポートを作るしくみです。 月次レポートを自動生成 月次レポートに、前月の実績値が閾値超過しているグラフを掲載 月次レポートに、前月の実績値からの予測値が1ヶ月以内に閾値超過するグラフを掲載 下2つは今回作ったgraphdというアプリケーションで実現しています。 ※オレンジが閾値、赤が予測 動作概要 ハートビーツでは HTTPS(HTTP)+JSON
Markdownを独自拡張してWordドキュメントを卒業する
こんにちはCTOの馬場です。 このたび納品ドキュメント作成で永らく使っていたWordを卒業し、 Markdownで書いてPDFで納める活動を始めたので公開します。 Wordを使っていると並行編集作業できない、改訂履歴追跡が難しいなどの課題があり、その解決のためにいろいろ模索してこの形になりました。 この仕組みには、こんなイイところがあります。 Markdownで書ける gitで差分管理、版管理される GitLab のマージリクエスト(GitHubで言うところのPull Request)を使ってレビュー・リリース管理できる GitLab CIで自動ビルドされる GitLab CI + Jenkinsで自動デプロイされる 以下のツール群を利用しています。 GitLab MkDocs HEARTBEATS Flavored Markdown extension wkhtmltopdf Jenki
MarkdownでSphinxできるようになったので試してみた（後編） - 意識の高いLISPマシン
この記事はドキュメンテーションツールAdvent Calendar (http://www.adventar.org/calendars/1196) の2日目です。 （まだまだ空欄だらけなので、執筆者も募集しています。） この記事は2部構成の2部目です。 1日目：概要の説明 MarkdownでSphinxできるようになったので試してみた（前編） - 意識の高いLISPマシン 2日目：実際に試してみた記録（いまここ） 今回は、実際にSphinxをインストールし、Markdownで文書が作成できるかどうかを試してみます。 なお、元ネタはこのプレゼンです（再掲）。 準備 Mac OS X上で作業。HomebrewでインストールしたPython2を使用します。 最近ターミナルをほったらかしていたので、まずHomebrewを整備します。 $ brew doctor $ brew update $ b
MarkdownでSphinxできるようになったので試してみた（前編） - 意識の高いLISPマシン
この記事は ドキュメンテーションツールAdvent Calendar の1日目です。 （まだまだ空欄だらけなので、執筆者も募集しています。） www.adventar.org 私はMarkdownで普段文書を書いているのですが、 この度ドキュメンテーションツール Sphinx でMarkdownが使えるようになったと聞いたので、軽く試してみたいと思います。 この記事は2部構成で2日にわたって執筆されます。 1日目：概要の説明（いまここ） 2日目：実際に試してみた記録（予定） 今回の記事では、概要をざっと説明します。 背景：Markdownの標準規格「CommonMark」の制定 MarkdownはGitHub Flavoredをはじめとして色々な方言があり、 まとまった仕様もなく混乱していました。 その中に現れたのが、CommonMarkというMarkdownの標準化規格です。 Commo
ドキュメントの構築
ドキュメントの構築¶ ドキュメントのヘルパーとガイドラインを提供すると、読者と作成者の両方の仕事を簡単に改善することができます。そのために、前節で学んできたことを活用していきます。 ドキュメント作成者の視点から考えると、ガイドと一緒に再利用可能なテンプレート集が提供され、それをプロジェクトの中でいつどのように使用するかという説明があると、この目標は達成できます。これをドキュメントポートフォリオと呼びます。 ドキュメント読者の視点から考えると、どのようなドキュメントが提供されるのかという展望が提供されると、楽にドキュメントを読むことができるようになりますし、必要なドキュメントを効率良く探して利用できるようになります。 ポートフォリオの構築¶ ソフトウェア開発のプロジェクトの中で作られるドキュメントには、ソースコードを直接参照するような低レベルなドキュメントから、アプリケーションの概要を伝える
virtualenv 環境で sphinx を試してエラーが出て先生に尋ねたら解決した - secretbase.log
Python のパッケージをインストールする場合、virtualenv を使うのが常識のよう なので、sphinxやその拡張もシステムに直接インストールせずに、virtualenv環境でやってみようと考えていました。 sphinxのビルド環境を virtualenv で用意する（ドキュメント毎にsphinxの拡張の導入も楽になることも期待) virtualenv 自体も 隠しディレクトリとして sphinx のビルド環境に含めたい そこで実験をするために、下記手順を行いました。 （環境は、Windows 7です) 適当なディレクトリに移動 ( %HOME%\work\temp とか ) に移動し下記コマンドを実行。 virtualenv .env .env\Scripts\activate.bat pip install sphinx sphinx-quickstart make.bat
Sphinxで更新履歴ページを作成
Sphinx でドキュメント管理している時に、みんなどうやって更新履歴ページを作成しているのか気になったので、既存プロジェクトを調べてみた。 履歴管理方法 大きく分けて2通りあった。 (主流)アプリケーションのChangeLog(や History や News)ファイルを Sphinx の更新履歴ページからインクルード (少数派)更新履歴ページにベタ書き 外部ファイルをインクルードしているプロジェクト 開発フローとしては、機能改修したら ChangeLog を更新すると、ドキュメントも連動する。 Sphinx 自体、この方法で履歴ページを管理している。 HTML : http://sphinx-doc.org/changes.html 元ファイル : http://sphinx-doc.org/_sources/changes.txt CHANGES ファイルを引っ張っている Pytho
SphinxをMarkdownで使い隊
Sphinxを、MercurialとPandocを組み合わせて Markdown記法で運用できるようにしたお話。
Sphinx で日本語を含む PDF 出力をする - 憧れ駆動開発
PDF を納める必要があったのでやった。Sphinx というか reST での日本語出力には若干の難があるらしい。けど、これも先人のとおりにやったら簡単にできた。 rst2pdf 方式 (8日目) Sphinx から PDF を生成してみよう (rst2pdf 編) - Hack like a rolling stone をまず参考にやってみた。pip install rst2pdf, PIL 環境構築, VLゴシックのようなフォントをいれる。 ja.json を作成して読み込ませる。PIL 環境の構築はハマりやすいから http://atasatamatara.hatenablog.jp/entry/20120803/1344001904 を参考にするといい。 結果としてはうまくいかなかった。後述の日本語のなんらかのパッチのはいった Sphinx だったらできたかもしれないけど、一部が文
Sphinx本の執筆体制について — そこはかとなく書くよん。 ドキュメント
Sphinx本の執筆体制について¶ この記事は ドキュメンテーション Advent Calendar 2013 の4日目の記事です。 すでにかなり時間がたってしまっておりますが、2013年9月に Sphinxをはじめよう という電子書籍をO'reilly Japan様から出版させていただきました。 もちろんSphinxで執筆しました。ここでは、その際に分かったtipsなどを共 有したいと思います。 のはずだったのですが、特別なことはなにもなく、普通にSphinxで書くだけで したので、Tipsというものはほぼありませんでした。(Sphinx後のフォント周り などでいろいろ問題があったようですが) そのため、今回はどういう体制で執筆したかについて説明したいと思います。 1. 執筆体制¶ 4人で執筆しました。 基本的に一人一章ずつ、それに加えて付録を適当に割り振って執筆していきま した。 2.
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
Standard MarkdownがCommon Markdow、そしてCommonMarkに
AWS Lambda で Sphinx
Markdownもはじめよう
SIerでもSphinxを使いたい！ 前編
baow.com
Bitbucket | Git solution for teams using Jira
Sphinx themes and presentation
GitHub - ryan-roemer/sphinx-bootstrap-theme: Sphinx Bootstrap Theme
