0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@Tand0

Ansibleモジュール開発で Sphinx や collection_prep を使わずドキュメントを自動生成する

0
Posted at

Ansibleモジュール開発で Sphinx や collection_prep を使わずドキュメントを自動生成する

はじめに

  • Windows 上での開発で wsl は使えるけど、
  • いちいちdockerとか立ち上げてビルドするのはなんかめんどうだなという人が、
  • Sphinx や collection_prep を使おうとしたら Windows 上では何かしらエラーが出たので、
  • とにかく、それっぽいものを見ることができれば良いかと思い、
  • 適当に開発しました
  • あと、markdown から HTML も作れるようにしています

どんな人向けか？

  • Sphinx や collection_prep を使うのが嫌な人
  • ソースコードをビルドするだけでわざわざ docker とか大げさに立ち上げるのがめんどい人
  • rst 形式が嫌な人
  • シンプルで良いからそれっぽいansibleモジュールのドキュメントを生成したい人
  • markdown からそれっぽい HTML を作りたい人

まずは ansible コレクションのダウンロード

$ ansible-galaxy tand0.makedoc

使い方例

galaxy.yml から markdown のドキュメントを作る

    - name: "create from galaxy.yml to README.md"
      tand0.makedoc.makedoc:
        src: "{{ item.src }}"
      loop:
        - src: collections/ansible_collections/tand0/makedoc/galaxy.yml
  • galaxy.yml から README.md もろもろを作成します
    • meta からもデータを収集します
    • `requirements.txt' からもデータを収集します
    • plugins/modules/*.py からドキュメントを生成して ./docs 配下に .md を置きます
  • src は元となる galaxy.yml です
  • 出力先は galaxy.yml と同じフォルダになります

galaxy.yml から markdown のドキュメントを作る(その2)

    - name: "create from galaxy.yml to README.md"
      tand0.makedoc.makedoc:
        src: "{{ item.src }}"
        overview: |
          ## Overview

          - You can connect via SSH using a language called TTL(Terawaros Tekitou Language), which is similar to teraterm macro, and ping other servers as stepping stones.

          ### MACRO for Terawaros Tekitou Lanugage

          - Usage
              - [The macro language Terawaros Tekitou Language (TTL)](./docs/syntax.md)
              - [TTL command reference](./docs/command.md)
      loop:
        - src: collections/ansible_collections/tand0/ttl/galaxy.yml
  • galaxy.yml から README.md もろもろを作成します
    • この書き方では overview が追加されています
    • overview によりちょっとした説明を先頭に追記することができます
  • src は元となる galaxy.yml です
  • 出力先は galaxy.yml と同じフォルダになります
  • overview は追加する説明です
    • 書き方は markdown です

１つの markdown を markdown に変更する

    - name: "create from md file to md file"
      tand0.makedoc.makedoc:
        src: "{{ item.src }}"
        dest: "{{ item.dest }}"
      loop:
        - src: ../docs/syntax.md
          dest: collections/ansible_collections/tand0/ttl/docs/syntax.md
        - src: ../docs/command.md
          dest: collections/ansible_collections/tand0/ttl/docs/command.md
  • 1つの makedown ファイルを markdown ファイルとしてコピーします
    • ただし、 makedown ファイルをコピーするとき、改行コードを LF にします
    • これは Ansible-galaxy の文書は LF にする必要があるためです
    • CRLF の場合 ansible-test sanity に引っかかります
  • src は元となる markdown です
  • dest は 出力先の markdown です

１つの markdown を HTML に変更する

    - name: "create from md file to html folder"
      tand0.makedoc.makedoc:
        src: "{{ item.src }}"
        dest: "{{ item.dest }}"
        css_file_list: ["codehilite.css", "language_html.css"]
        extensions: ["tables", "fenced_code", "attr_list", "codehilite"]
        replace_list:
          - before: 'src="./docs/([^"]+)'
            after: 'src="\1'
          - before: 'href="./docs/([^"]+)'
            after: 'href="\1"'
          - before: 'href="([^"]+)\.md'
            after: 'href="\1.html'
      loop:
        - src: ../README.md
          dest: ../nextnextping/dist/nextnextping/_internal/
  • 1つのmarkdownファイルをHTMLに変換します
  • src は元となる markdown です
  • dest は 出力先のフォルダ名です
  • css_file_list は出力する css ファイルの名称です
    • codehilite.css と language_html.css は無ければ自動生成します
    • それ以外の css を指定した場合は、自分で作る必要があります
  • extensions は markdown packageが要求するオプションです
    • 詳しくは python markdown packageを参照してください
    • このコレクションは要するに markdown をラップしてansibleらしく冪等性確認しているだけです
  • replace_list は出力した HTML を正規表現で置換する場合に使います
    • Ansibleではlineinfile 、replace などのタスクがありますが、タスクを分けると冪等性が担保できなくなるので追加しました

フォルダ上の markdown を HTML に変更する

    - name: "create from folder to html folder"
      tand0.makedoc.makedoc:
        src: "{{ item.src }}"
        dest: "{{ item.dest }}"
        css_file_list: ["codehilite.css", "language_html.css"]
        extensions: ["tables", "fenced_code", "attr_list", "codehilite"]
        replace_list:
          - before: 'href="([^"]+)\.md'
            after: 'href="\1.html'
      loop:
        - src: ../docs/
          dest: ../nextnextping/dist/nextnextping/_internal/
  • markdown の置かれているフォルダを検索して HTML に変換します
  • フォルダ上の画像や動画ファイルもまとめてdestフォルダにコピーします
  • src は元となる READMEです
  • dest は 出力先のフォルダ名です
  • css_file_list は出力する css ファイルの名称です
    • codehilite.css と language_html.css は無ければ自動生成します
    • それ以外の css を指定した場合は、自分で作る必要があります
  • extensions は markdown packageが要求するオプションです
    • 詳しくは python markdown packageを参照してください
    • このコレクションは要するに markdown をラップしてansibleらしく冪等性確認しているだけです
  • replace_list は出力した HTML を正規表現で置換する場合に使います
    • ここでは同一リンク上への .md へのリンクを .html に変換しています
    • Ansibleではlineinfile 、replace などのタスクがありますが、タスクを分けると冪等性が担保できなくなるので追加しました

参考

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?