自社では Sphinx というドキュメントツールを利用しているのですが、残念ながらこれに付属している検索機能の日本語検索はかなり厳しいです。また残念ながら Sphinx 開発側も検索周りを改善するという予定は直近ではないようです。 そして検索というのはとても難しい技術なため自分のような素人では導入して「普通に期待する動作」をさせるまでの距離はとても遠いです。 ただ、なんとかして日本語全文検索を実現したいという思いはここ10 年くらいずっと思っていました。これは自社の Sphinx テーマを作ってくれている社員ともよく話をしていたのですが、どうしてもリソースをつぎ込めずにいました。 まとめ日本語検索に対応している Meilisearch を採用したドキュメントスクレイパーの実行は GItHub Actions (Self-hosted Runner) を採用した自社 Sphinx テーマの検
モチベーション ドキュメントツール Sphinx から出力した HTML オンラインドキュメントに日本語対応の全文検索機能を追加したい。 結果 オンラインドキュメントと日本語全文検索 前提 日本語全文検索に対応する OSS を利用する ドキュメントツールは Sphinx を利用する Sphinx の検索バーを置き換える サーバレスの検索は諦める サーバ運用を検討する 企業利用前提なので費用がかかっても良い 検索は難しいので検索部分は頑張らない 完璧は求めない reStructuredText を解析するのではなく HTML を解析して処理する Meilisearch を採用 いろいろ調べたりしていたが Meilisearch が良さそうと判断した。 Meilisearch 日本語検索に対応している Rust で書かれており性能がでそう Rust であれば問題が起きた際、会社でなんとかできる
こんにちは。阿形です。 今回の記事は特殊な事情でちょっとややこしいので状況を説明しておきます。 弊社のドキュメント作成環境 弊社ではドキュメント作成にSphinxを使用し、GitLabでバージョン管理を行っています。 さらにGitLabとNetlifyと連携させ、Netlify上でSphinxのドキュメントをビルド、そのままWebに公開することがあります。 更に追加条件で、Sphinxのドキュメント上で図を描く際に、blockdiagを使用することがあります。 blockdiagで描く図自体は特に問題はないのですが、図中に日本語の文字を入れるときに問題が発生します。 blockdiagは日本語を使用する場合には、blockdiag_fontpathという変数に使用するフォントへのパスを絶対パスで設定しておく必要があるためです。 通常、ローカルで使用しているだけならばローカル環境のフォントへ
2. 自己紹介 山口能迪（やまぐちよしふみ） id : ymotongpoo 「とんぷー」と呼んでください OSSのドキュメント翻訳をしています Tornado （軽量Webフレームワーク） Redis （高機能KVS） Jinja2 （テンプレートエンジン） など 3. 自己紹介：渋川よしき 仕事 大手製造業の社内SE 社外で技術習得して社内で楽をする 参加コミュニティ SphinxUsers.jp会長 翻訳ハッカソンとかを継続開催予定 日本XPユーザグループ代表 とちぎRuby Python温泉(系) 11/14にPython Hack-‐a-‐thon 今年出した本 IT業界を楽しく生き抜くための つまみぐい勉強法(技術評論社) エキスパートPythonプログラミ
Sphinxは非常に素晴らしいドキュメント生成ツールです。 この素晴らしいツールを社内で流行らせようと頑張ったのですが、誰も使ってくれません。 みんながどんなタイミングで、Sphinxを諦めてしまうのか振り返ってみました。 reStructuredTextがわからないし、覚えたくもない デフォルトのテーマが見にくいからやめる sphinx-quickstartの設問が多すぎて途中でやめる ドキュメント作成のたびにconf.pyを編集するのが面倒なので使わなくなる ドキュメント確認のたびにmake htmlが面倒なので使わなくなる 最近はJupyterでドキュメント書くので・・・ こんなところでしょうか。 たぶん、Sphinxがいまいち流行らないのも、ここら辺が理由が大きいんじゃないかと思います。 Markdownを使う 残念ながらマークアップ言語の主流はreStructuredTextでは
gitlab.comは自前でDocker image登録できたり、CI持っていたりと便利ですね。しかも、privateレポジトリもお金かからないという太っ腹。 技術書典2に向けたレポジトリはgitlab.comで管理しています。 今回は共著者にPython使いが多いためSphinxを使って書いているんですが、Sphinxはcommon markでも書けるのでmarkdownでも文章を書くことが出来ます。 前回の記事では、数式入りのmarkdownからPDFを生成するDocker imageを作りましたが、それを使うと簡単にGitlab-CIでPDFが生成できます。 chezou.hatenablog.com やり方は簡単、あなたのSphinxのプロジェクトに、以下のような.gitlab-ci.ymlを書くだけ。もちろん、必要に応じてpathsは変更してください。 image: chezou
先日GitHubで嬉しいアップデートが行われ、 masterリポジトリの/docs以下をGitHub Pagesで公開できるようになりました。 これまでGitHub Pagesを利用するにはgh-pagesブランチを作成する必要がありましたが、プロジェクトのソースコードと一緒にドキュメントを管理できようになったのはかなり嬉しいです！ そこで今回は、以前書いたAndroidアプリをDockerでビルドする記事をもとに ドキュメント生成ツールであるSphinxのビルドをDockerでやってみました。 これでプロジェクト用のドキュメントを作ってじゃんじゃん公開していきましょう。 Sphinxとは SphinxはPython製のドキュメント生成ツールです。 ドキュメント生成ツールとしてはかなり有名でして、Pythonの公式ドキュメントでも利用されています。 基本的なドキュメント作成の流れとしては、
私はソフトウェア開発を主体とするエンジニアで、 クラウドサービスの開発・運用 分散処理技術の検証とサービス利用の検討 社内の開発支援環境の開発・運用 などの業務に従事していますが、今回の記事は業務とは直接的な関係は無く、私が会社で勝手自発的に行っている取り組みについて書きたいと思います。 昨今、インターネットは生活に深く浸透し、クラウドサービスを利用することで安く簡単にWebサービスを開発、公開できるようになりました。Web技術の進化や流行の移り変りも非常に激しく、既存サービスの機能追加や新規サービスの開発は頻繁に行われています。それは弊社も例外ではありません。 このような開発の現場では、リーンソフトウェア開発への取り組みなど開発手法の最適化が積極的に行われ、様々なベストプラクティスが生みだされています。それらのベストプラクティスには、 継続的インテグレーション や 継続的デプロイメント
渡辺です。 開発者の間ではgithub式Markdownでドキュメントを書くのが主流となっている昨今ですが、エンドユーザ向けのドキュメントとなると出力フォーマット・版管理・クロスリファレンスなど、機能的にもう少し欲しいところです。しかし、Wordといった専用の文書作成ソフトを使うほどでもないし、表計算ソフトを使うのは論外だと思われます。 そんな要求を満たすツールはSphinxです。今回は、Sphinxを利用してドキュメントを生成し、Jenkinsによる自動ビルドでHTML形式のファイルを作成し、S3へのリリースする手順を解説してみます。Sphinxは静的ファイルを生成するため、S3やCloudFrontと相性良く利用できるソリューションです。 Sphinxとは？ Sphinxは、ドキュメント生成ツールです。SphinxではPythonで採用されているreStructuredText(reS
TOPICS Python 発行年月日 2013年09月 ISBN 978-4-87311-648-8 FORMAT PDF EPUB 本書には改訂版があります。 Officeツールを使用していて、思うようにならずストレスを感じる事はありませんか？あるいは、印刷用の資料を見ている時に、Webブラウザで閲覧しやすいフォーマットになっていて欲しいと思ったりはしませんか？ 本書はPythonで標準的なドキュメント作成ツールとして利用されているSphinxの入門書です。Windows、OS X、Linux（Ubuntu）を例に、Sphinxの概要からインストール、基本的な利用法について。またSphinxからLaTeXを経由してPDFを作成したり、EPUBフォーマットの電子書籍を作成する方法を、初めて触れる方にもわかりやすく紹介しています。 なお本書はEbook版のみの販売となります。 はじめに 本
昨日の日記の続きです。 Sphinxでドキュメント生成（Windowsでの始め方） - torutkの日記 今日は、SphinxでPDF形式のドキュメント生成を行います。PDF形式に出力するには、TeX経由で行う方法とSphinxのrst2pdf拡張で行う方法があるようです。 SphinxでPDFファイル作成 — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会(Sphinx日本ユーザー会ドキュメントより） 上記ドキュメントの比較によると、rst2pdfがよさそうなので、これを使ってPDF出力の仕組みをWindowsに整えます。なお、昨日同様、インターネットに接続していないPCでも環境を整えられるよう、必要なものをダウンロードしインストールします。 Windows上でrst2pdfを用意する PythonのReportLab Toolkitモジュール rst2pdfが
Sphinxは、HTMLだけではなく他の形式でも出力可能だ。今回はPDFを生成出来るようにしてみた。 Windowsでの導入方法については下記のエントリが詳しい。 Sphinxでドキュメント生成-PDF（Windowsでの始め方） - torutkのブログ 今回はMacで試してみた。動作環境は下記の通り MacOS X 10.6.8 Python 2.6 (MacPorts) Sphinx 1.0.7 rst2pdf 下記の手順に従ってrst2pdfをインストールして設定を行った。 rst2pdf拡張を使ったPDFファイル作成 — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会 % sudo /opt/local/bin/easy_install-2.6 rst2pdf make pdfコマンドを叩いたら、下記のエラーが発生した。 [ERROR] styles.py
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
