acokikoy's notes

最近気になる=[NoCode, Shopify], I am..=[Python, ウクレレ, マニュアル車, CMS] LoveなWebディレクター

イベント参加ログ》みんなのPython勉強会#58 @2020年6月10日(水)19:00〜21:00 オンライン開催

みんなのPython勉強会#58 の聴講メモ。
YouTubeライブ配信によるオンライン開催で、テーマは「Python製ドキュメント生成ツールSphinx丸わかり」。
当日誰かのtweetだかslackだかで気づいて飛び入り聴講した。予想を越える面白さで参加して良かった。

startpython.connpass.com

Twitter #stapy%20lang%3Aja%20until%3A2020-06-15%20since%3A2020-06-10&src=typed_query)

  • どりらん@patraqusheさん

    • 非エンジニア
    • fin-py - connpass
    • Sphinxとは
      • プレーンテキスト
      • reST restructured text(Wiki記法みたいなもん?)
      • Sphinxのよいところ
        • ❇️ソースがテキストなのでバージョン管理できる
        • 拡張視野類
        • toctreeベース(目次:文書構造の階層管理)
      • Sphinxで書かれたもの
      • どりらんさんとSphinx
        • Quantopian日本語翻訳プロジェクト
        • 執筆
      • Sphinx-Users.jp 日本のSphinxユーザ会(世界的にも強力なユーザ会)
        • ❇️質問することで得られる利点
          • 自己解決以上のソリューションが得られる
          • いずれ詰まった時にきける安心感
        • Slackで質問
        • Sphinx翻訳ハッカソン → 今だけリモート開催
    • OSSに貢献したい?
      • テストユーザとしての貢献
    • 技術書書く時に使っている
  • 吉政忠志さん

    • この前BPStudy#152 に登壇されてた「ITエンジニアのための企画力と企画書の教科書」の人
    • PythonED ・・Pythonicを理解した人材が育成されるよう
    • Python3エンジニア認定データ分析試験(PythonCDA) データ分析の基礎や方法を問う試験
    • 基礎試験の上位試験、データ分析の上位試験を企画中
  • 波田野裕一@tcshさん

    • 発表資料: https://twitter.com/tcsh/status/1270694581357604866
    • 以前: 手順書をHTMLやxmlで書いたりしていた
    • Sphinx
    • JAWS-UG CLI専門支部
    • AWS CLI公式リファレンスはSphinxでビルドされている
    • ドキュメント作成を人と機械で分担する
      • reSTructured Text
      • "人にしか書けない部分"を人が書く
      • 「機械がかけるところを機械に書かせる」考え方だと人の工数は減らない
      • "人が書かなくても良いところ"を機械に書かせる
    • 機械に書かせる
      • ヒアドキュメント
      • catコマンド
      • sedコマンド
    • Sphinxの重要な機能。この3つを意識的に使うのがコツ。
      • インクルード機能
      • 置換機能
      • toctree(文書構造を決める)
    • どう構造化するかを常に考える
      • reSTで書く
      • 何を作りたいか全体像を考える
      • 変化が少なく寿命が長い文書にこそ工数をかけるべき
      • 陳腐化が速い文書は機械に書かせる (週報とか)
      • ❇️Sphinxでドキュメントを書いていると脳内も構造化されていく
  • @tk0miyaさん

    • 発表資料: https://twitter.com/tk0miya/status/1270677674646630400
    • プジョー(206?)の人。Sphinx
    • Sphinxはドキュメントビルダーの1つ
    • 主な機能
      • 見た目が整う(イイ感じのテーマで)
      • クロスリファレンス機能
      • 形式変換
        • HTML, PDF, text, EPUBなどなど
      • 拡張パッケージ
      • 使い道
        • Webページ、リファレンス、書籍
    • コードからドキュメント生成
      • プログラムを書き換えるとリファレンスも自動更新されて欲しい → Sphinx
      • autodoc拡張(モジュール単位)
        • Pythonモジュールを原稿として扱う。
        • クラス構造や関数の引数情報, docstring、型アノテーションを読み取ってドキュメント化
        • conf.py でautodoc有効化
        • docstringに引数の説明を書く
          • :param x: 数値1
          • #: 円周率 ・・・classのメンバ変数
        • アノテーション def sum(self, x: int, y:int) -> int:
      • intersphinxで他のSphinxドキュメントへのリンクが貼れる(Python公式とかnumpyとかへ)
      • 全体的な説明をドキュメントに書いておく
      • ❇️プログラムが大きくなってきたら autosummary, apidocなどの拡張(プログラム単位でのドキュメント化)
    • Sphinx-Users.jp — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会
    • 個人スポンサー