オンラインドキュメントと日本語全文検索
自社では Sphinx というドキュメントツールを利用しているのですが、残念ながらこれに付属している検索機能の日本語検索はかなり厳しいです。また残念ながら Sphinx 開発側も検索周りを改善するという予定は直近ではないようです。 そして検索というのはとても難しい技術なため自分のような素人では導入して「普通に期待する動作」をさせるまでの距離はとても遠いです。 ただ、なんとかして日本語全文検索を実現したいという思いはここ10 年くらいずっと思っていました。これは自社の Sphinx テーマを作ってくれている社員ともよく話をしていたのですが、どうしてもリソースをつぎ込めずにいました。 まとめ日本語検索に対応している Meilisearch を採用したドキュメントスクレイパーの実行は GItHub Actions (Self-hosted Runner) を採用した自社 Sphinx テーマの検
Please don't write your documentation in Markdown
March 23, 2020 Please don't write your documentation in Markdown Please don't write your documentation in Markdown. Please. I'm begging you. Markdown is tolerable for short documentation, like a readme.md. Past that, it's the wrong tool for the job. Markdown is about formatting, not information Markdown is just a way to write simpler, nice looking HTML. There is direct mapping between _foo_ and <e
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 10周年に寄せて #sphinx10th - Hack like a rolling stone
本日、Sphinx-1.7.2 をリリースしました。いくつかのバグが修正されているので、試してみてください。 pypi.python.org さて、リリースするまですっかり忘れていましたが、本日 3月21日は Sphinx の誕生日です。しかも、なんと 10周年です。 Release 0.1.61611 (Mar 21, 2008) ================================ * First public release.github.com Sphinx と僕の (だいたい) 10年間 僕が Python を使いはじめた頃から、既に Sphinx はよく使われていたので、かなり古くからあるツールだと思っていたのですが、実は 僕の Python 暦(2010年ごろ)とそんなに変わらないのですね。実際、Python を使いはじめた頃に 0.6.6 を使ってみたり、1.0
Shibu's Diary: 「Real World HTTP」が出版されます！
昨年から書いていたReal World HTTPがAmazonのページに表示されるようになりました。最初にコミットしたのは昨年の8/1ですが、たぶん、その数ヶ月前から書き始めていたと思うので、ほぼ丸一年です。途中でASCII.jpのシステムプログラミングの連載が始まったり、Software DesignにSphinxについて寄稿したり、もう１つ別の翻訳の企画があったり、三女が7/4に生まれたり、なかなかハードな一年間でした。 なお、表紙は皆さんが知っているものとはちょっと違うのですが、系統的に一番近いのがハシビロコウさんらしく、和名もそれしかないそうです。狙っていたわけではなく、そもそも出版時期にはアニメも終わってしまっているし、話題の動物は辞めたほうが良さそう、という話をしていたのですが、偶然これが選ばれました。 本の内容の紹介 裏表紙の紹介はこんな感じです。 本書はHTTPに関する技術
「Sphinxをはじめよう 第二版」が出ます - Hack like a rolling stone
みなさん、Sphinx 使ってますか? Python や Linux カーネルのドキュメントでご存知の Sphinx の書籍、「Sphinxをはじめよう」が改訂されます。 今週末の #技術書典 で僕らが書いた #Sphinxをはじめよう の第二版が発売されます。しかも今回は紙媒体！(電子版もあるよ)。これからSphinxを触ってみようかなと思っている方におすすめです。細かな加筆をしているので、第一版をお持ちの方にもおすすめです。 #sphinxjp— Takeshi KOMIYA (@tk0miya) 2017年10月17日 #Sphinxをはじめよう の第二版は 1) Sphinx-1.6 に合わせて加筆 2) 基本のマークアップの説明をアップデート 3) みんな大好きmarkdownの説明をAppendixとして収録 4) 画像系のツール/サービスとの連携まわりの章を追加 とあれこれい
Sphinx から完全に reStructuredText を追い出した話 - Hack like a rolling stone
いくつかの記事で紹介されているとおり、 recommonmark を使うと Sphinx で markdown を使うことができます。 Software Design 2016年4月号 Markdownで始めるSphinx MarkdownでSphinxできるようになったので試してみた（前編） - 意識の高いLISPマシン Markdownで書けるSphinxの構築 - Qiita しかし、recommonmark を利用しても、ドキュメント構造(toctree)を記述するためには部分的に reStructredText を使う必要がありました。 .. toctree chapter1 chapter2 chapter3 これは、文法を拡張する仕組みを持たない markdown の (commonmark の)構造上、仕方がないのですが、せっかく markdown でドキュメントを書いてい
Sphinx に mypy の type annotation を導入した話 - Hack like a rolling stone
今年はアドベントカレンダーにも参加していないし、こたつに入ってだらだら過ごそうかと思っていたら、なんか書けと煽られました。年末ですね。 @tk0miya qiita の記事まだー？— Tetsuya Morimoto (@t2y) 2016年12月25日 何を書こうか思考をめぐらした結果、mypy を Sphinx に導入した話でも書くことにします。 mypy については @t2y の 紹介記事 、翻訳記事が非常に参考になりました。 ですので、この記事は @t2y へのアンサーソングです。 なお、「導入した話」と名付けてはみたものの、まだ 100% 対応したというわけではないので、試行錯誤の様子と愚痴を書き留めていきます。 Sphinx に type annotation をつけてみた Sphinx では現在、 master ブランチに対して type annotation がつけられてい
リポジトリのコミット履歴を表示する sphinxcontrib-vcs を作りました - Qiita
Sphinx で管理しているドキュメントの履歴や差分内容を気軽に確認できるようにするための Sphinx 拡張です。 Git と Mercurial に対応しています。Python 2/3 両対応ですが、Mercurial は Python 3 対応していないので Python 2.7 環境でしか動作しません。 以下 PyPI とそのドキュメントになります。 https://pypi.python.org/pypi/sphinxcontrib-vcs/ ドキュメント: https://pythonhosted.org/sphinxcontrib-vcs/ 経緯 類似の Sphinx 拡張として sphinx-git があります。当初は私もこの拡張機能を使っていました。私の用途として、差分内容を表示する機能を追加したかったのと sphinx-git のメンテナンスがあまり活発ではないのもあり
Bitbucket Pipelines を使って、レポジトリが更新されたら、S3経由してHTML更新 - Qiita
構成要素 Bitbucket レポジトリ (git or hg) Sphinxのドキュメンテーション AWS S3 バケット (データ保存用) Webサーバ(nginx) (Basic認証を行う) Bitbucket Pipelines (レポジトリのPushをキーにSphinx build & S3にPush) Dockerコンテナ Pipelineで使用するコンテナ 補足 Web静的ホスト・認証 AWS S3 には、静的Webホスティングの仕組みがありますが、Basic認証が掛けられないため、別途Webサーバを準備し、S3の静的ホスティングにリバースプロキシする。 S3の閲覧権限をIPアドレスで制限する。 つまり、IP制限のみならWebサーバを別途準備する必要はない。 Pipelines と Dockerコンテナ Bitbucket Pipelinesは、最近正式にサービスが始まった、
自分用技術メモの作成が捗ったSphinxのあれこれについて - Qiita
はじめに この記事はHamee Advent Calendar 2016の17日目の記事です。 少し前から個人的にSphinx（Python製のドキュメンテーションツール）に触れていて、試しに自分用の技術メモの作成にSphinxを使ってみたら思った以上に捗ったので、その際に使った機能や拡張機能について書いていきます。 注意 この記事ではSphinxの詳細についてはほとんど紹介しません。 あくまでこんな機能・拡張機能を使ったら便利だったよ！といった ポエム 内容の記事となっていますので、あらかじめご了承ください。 TOCツリーのおかげで見通しが良く管理しやすい メモを1つのファイルに書いていくと、あれもこれもと書いているうちに次第に内容が膨大になっていき、後で振り返りをしようと思ったらメモが読みづらいとか内容を追加しようと思ったらどこに何が書いてあるかわかりづらい…なんてこともあるかと思いま
reStructuredText vs Markdown for documentation
In this post I am going to share my experience of using Markdown and reStructuredText (RST) for technical documentation. As a library developer I have to write a fair amount of it, for example, the fmt library documentation, and I’ve used both languages extensively. In fact, I’m writing this blog post in Markdown. At first sight RST and Markdown look very similar. Both are lightweight markup langu
ドキュメントの継続的な開発方法 | IIJ Engineers Blog
私はソフトウェア開発を主体とするエンジニアで、 クラウドサービスの開発・運用 分散処理技術の検証とサービス利用の検討 社内の開発支援環境の開発・運用 などの業務に従事していますが、今回の記事は業務とは直接的な関係は無く、私が会社で勝手自発的に行っている取り組みについて書きたいと思います。 昨今、インターネットは生活に深く浸透し、クラウドサービスを利用することで安く簡単にWebサービスを開発、公開できるようになりました。Web技術の進化や流行の移り変りも非常に激しく、既存サービスの機能追加や新規サービスの開発は頻繁に行われています。それは弊社も例外ではありません。 このような開発の現場では、リーンソフトウェア開発への取り組みなど開発手法の最適化が積極的に行われ、様々なベストプラクティスが生みだされています。それらのベストプラクティスには、 継続的インテグレーション や 継続的デプロイメント
Sphinx: sphinx-autobuild で執筆作業の効率を上げる - CUBE SUGAR CONTAINER
先日 SphinxCon JP 2015 で発表の機会に恵まれたんだけど、意外と sphinx-autobuild について知られていなかったようなのでブログにも書いてみることにする。 まず、内容を確認するのに HTML を使っている場合、通常であれば Sphinx の執筆作業は以下の工程の繰り返しになるとおもう。 この繰り返しは本当にめんどうくさいから、執筆への集中を阻害する原因になる。 ドキュメントのソースファイルを編集する Sphinx でビルドする ブラウザにフォーカスを移す ブラウザをリロードする 内容を確認する そこで sphinx-autobuild を使うと (2) から (4) までの作業を自動化してくれる。 これで執筆に集中できるから効率も上がるというもの。 使ってみよう 検証した環境には Mac OS X を使っている。 $ sw_vers ProductName:
LINE DEVELOPER DAY 2016 開催のお知らせ « LINE Engineers' Blog
LINE株式会社は、2023年10月1日にLINEヤフー株式会社になりました。LINEヤフー株式会社の新しいブログはこちらです。 LINEヤフー Tech Blog saegusa2017-04-16Yoshihiro was a network engineer at LINE, responsible for all levels of LINE's infrastructure. Since being named Infra Platform Department manager, he is finding ways to apply LINE's technology and business goals to the platform. こんにちは。LINEでネットワークやデータセンターを担当している三枝です。2017年1月にJANOG39で登壇する機会を頂きましたので、今回
WEB+DB PRESS vol88にMQTTの記事を書きました — そこはかとなく書くよん。 ドキュメント
WEB+DB PRESS vol88にMQTTの記事を書きました¶ 2015年8月22日発売の WEB+DB PRESS vol88 に 速習 MQTT というタイトルでMQTTに関する記事を書かせていただきました。 内容は以下の通りです。 MQTTとは MQTTの利用場面 MQTTの特長 その他のプロトコルとの比較 MQTTを使ってみる 速習、というタイトルの通り、利用場面や特長の説明がメインの、MQTTという聞きなれないプロトコルの内容を一通り説明する内容になっています。一応MQTTを使ってみる、という箇所でMQTTを使うアプリをpythonで実装してみていますが、 eclipse paho のおかげもあり、非常に短い行で実装が完了しており、分量は正直あんまりです。 最近すっかりバズワード化してしまい、「MQTTはIoT時代の主役となるプロトコルだ」「MQTTで全部できる」というような
JUS関西 Sphinxワークショップ@関西 Sphinx事例紹介
2015/10/31に開催されたSphinxワークショップ@関西(https://japanunixsociety.doorkeeper.jp/events/32899)の発表資料です。Read less
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
https://www.freia.jp/taka/blog/sphinxjp-camp-20180108/index.html
Sphinx(reStructuredText)のエディタ選択の話 | Tech Blog | CRESCO Tech Blog
https://www.freia.jp/taka/blog/sphinx-dev-remove-2to3/index.html