Sphinx

はじめに 七尾百合子さん、お誕生日 6日目 おめでとうございます！ nikkieです。 発表資料はSphinx（sphinx-revealjs）で作っている私ですが、リリースビルドで想定外のwarningがあったら1そこで止められると気づきました。 目次 はじめに 目次 できたもの：発表資料をビルドしてリリースするパイプラインを落とす sphinx-buildの--fail-on-warningと--exception-on-warning 脱線：--exception-on-warningはなぜ登場した？ 終わりに できたもの：発表資料をビルドしてリリースするパイプラインを落とす 発表資料は…

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…

概要 Sphinx、GitHub Actionsを使用してGitHub Pagesにドキュメントをデプロイするまでをやってみる。 内容 （参考）Sphinx公式 https://www.sphinx-doc.org/ja/master/ リポジトリ作成して、GitHub Pagesの「Source」を「GitHub Actions」に変更。 リポジトリにフォルダやファイルを作成していく。 今回は以下のようなフォルダ構成とした。 .github/workflows/shinx.ymlにGitHub Actionsで実行する内容を記載 python環境にsphinxやsphinxの拡張機能をインス…

目次 目次 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の中の外部リンクを、ブラウザの新しいタブで開くように設定する拡張を公開しています…