Sphinx

aptpod Advent Calendar 2024 の12月9日の記事です。 本日は、テクニカルライターの篠崎が担当します。 当社では今年、ドキュメントサイトをリニューアルし、複数のプロダクトのドキュメントを1つのウェブサイトに統合しました。 これにより、読み手は全体を俯瞰しながら各製品の詳細に読み進めることができるようになりました。 また、私のような制作側にとっては、ページ間のリンクを張りやすくなりました。内容の重複も減らすことができ、更新作業もしやすくなりました。 統合されたドキュメントサイト 製品ドキュメントの作成にはSphinxを使っています。これまでプロダクトごとに別々だったSp…

Today I learned。Sphinx拡張開発の中で知ったことです。 目次 目次 Sphinx拡張からロギング 太字のログ出力の実装 ビルダー bold()の実装 終わりに P.S. sphinx-revealjsのロギング Sphinx拡張からロギング 自作拡張の中でロギングしてみようとなり1、sphinx.util.loggingを触りました。 getLogger()してロガーインスタンスを得て、重要度ごとのメソッドにメッセージを渡します（標準モジュールloggingと似ていますね2） logger = logging.getLogger(__name__) logger.info(…

はじめに 香織先輩 & ドラえもんさん、お誕生日おめでとうございます！ nikkieです。 気になっていたSphinx拡張を試しました。 目次 はじめに 目次 sphinx-copybutton 設定例 実は出会っていたsphinx-copybutton 実装を少しだけ 終わりに sphinx-copybutton ドキュメンテーションツールSphinxで、ビルドしたHTML中のコードブロックをボタン一発でコピー可能にする拡張です。 画像右上にご注目 使い方は、インストールして有効にするだけ。 $ pip install sphinx-copybutton # conf.py extensio…

Python のソースから仕様書を生成する方法を紹介します。 仕様書は、クラスごとに分けたウェブページとして生成します。 生成には、Sphinx を使用します。 Sphinx の拡張機能 autodoc、sphinx-immaterial を使用して簡単に実現します。

目次 目次 attakeiさんによるsphinx-revealjs sphinx-revealjs with sphinx-new-tab-link 必要な設定 reST原稿の例 終わりに P.S. コマンドアップデート版 attakeiさんによるsphinx-revealjs sphinx-revealjsは、SphinxでReveal.js製スライドを生成できるライブラリです。 生みの親のattakeiさんによる記事があります。 私はsphinx-revealjsを愛用しています。 月一ペースで登壇しているので、ひょっとすると日本一（まさか世界一！？）sphinx-revealjsを使って…

はじめに Act-4、よかった。想いのこもったツイート見るたび泣いてます。nikkieです。 このところSphinx熱が再燃しており、本日もSphinxネタです。 目次 はじめに 目次 Sphinxの自作拡張におけるTranslator 結論：現時点の理解 Sphinxの拡張 TranslatorとBuilder Translator Builder 『マスタリング docutils』より 終わりに P.S. わかりやすかった記事 Sphinxの自作拡張におけるTranslator SphinxでビルドしたHTMLの中の外部リンクを、ブラウザの新しいタブで開くように設定する拡張を公開しています…

はじめに エミリーちゃんのことますます すきすきになりました、nikkieです😭 ドキュメンテーションツールSphinx1にはテーマという機能がありますが2、自作できると知り手を動かしました。 目次 はじめに 目次 Sphinxのテーマを作る 強調箇所の色を変えるテーマを自作する _themes下に配置 theme.conf static/custom.css 自作テーマを当てた結果 終わりに Sphinxのテーマを作る Sphinx-Users.jp にズバリなページがあります。 Sphinxはテーマという形で、ドキュメントの見た目を変更することができます。 ここに沿って、ドキュメントの見た…