Documentation/Migrate
目录
DocBook から RST へのドキュメント移行概要
以前は、<service>-api リポジトリを DocBook から RST に移行しました。これらは、API への変更内容を把握するためにコントリビュータ開発者が参照する API リファレンスドキュメントでした。そのため、そのドキュメントの履歴は仕様として作成されました。swift や nova 以外のプロジェクトも追加されるにつれて、同様のドキュメントを作成するようになりました。それらは https://docs.openstack.org/api/api-specs.html で HTML として出力されます。しかし、<project>-specs リポジトリが利用可能になったため、それらのリポジトリに移行することが理にかなっています。その移行において、DocBook/WADL ではなく RST に移行することも理にかなっています。
移行規則
OpenStack Documentation Contributor Guide の RST マークアップ規則に従ってください。
見出し
RST ファイルの最初のタイトルは、上下にイコール記号を使用します。2 番目のタイトルはチルダを使用します。3 番目のタイトルは、ダッシュの連続を使用します。必要に応じて、リライトまたは再構成することで、見出し 4 を使用する必要がないようにしてください。
======== Heading 1 ======== Heading 2 ~~~~~~~~~ Heading 3 ---------
ファイル名
原則として、出力される HTML ファイルのリダイレクトを回避するために、xml:id を同一に保ちたいと考えています。ただし、同時に ch_ や section_ という命名規則をなくし、ページベースのトピック指向のアプローチを採用したいと考えています。そのため、まず XML:ID を使用し、XML:ID に ch_ または section_ が含まれている場合は、プレフィックスを削除します。
相互参照
正確なタイトルを持つ必要がないように、相互参照を行う場合は :ref: を使用してください。そのため、アンカーを作成するためのマークアップを追加する必要があります。例:
.. _dashboard-project-tab
可能な場合は、これらの相互参照に既存の XML:Id を使用してください。
また、intersphinx は多くのコントリビュータ開発者ドキュメントで有効になっている拡張機能ですが、エンドユーザーガイドや管理者ユーザーガイドにはまだ intersphinx の要件はありません。ガイドを追加するにつれて、それを調査します。
図と画像
図は、配信物自体と同じディレクトリの /figures/ ディレクトリに保存します。
注釈と注意書き
変換で Note が見出しとして出力された場合は、.. note:: ディレクティブを使用するように変更してください。
コードブロック内の行番号
ファイルに多くのコードブロックがある場合は、ファイル全体の行番号を設定してください。各コードブロックには、.. code-block:: ディレクティブの後に :linenos: が必要です。コード自体は、:lineos: 行と同じレベルでインデントする必要があり、ファイルの先頭にこのディレクティブが必要です
.. highlight: python :linenothreshold: 5
これにより、5 行を超えるコードブロックには行番号が付けられます。
移行の問題点
Sphinx テーマ、openstackdocstheme のバグまたは不足機能のリスト: https://bugs.launchpad.net/openstack-manuals/+bugs?field.tag=openstackdocstheme
:guilabel: のようなインラインセマンティックマークアップの行末に改行を挿入できますか？ 例:
#. Select the volume to add to an instance and click :guilabel:`Edit Attachments`.
その行は 79 文字を超えるため、Attachments`. は 2 行目に配置する必要がありますが、そうすると HTML 出力が正しくありません。
RST ドキュメントは .rst 形式でファイルをビルドする際に 79 文字の制限を課します。テーブルがその制限を超える場合、リストテーブルロールを使用して、79 文字の制限を超えずに新しいテーブルでコンテンツを作成できます。問題は、OpenStack サービスによって生成され、コマンドの結果として返されるテーブルです。これらのテーブルは、+、-、および | 文字で構成されています。リストテーブルロールによって作成されたテーブルには、行、列、およびセルを形成する実線が表示されます。コンテンツは似ていますが、ユーザーは +、-、および | 文字で構築されたテーブルではなく、実線でテーブルが表示されることに驚くかもしれません。
テーブル内の大規模なコンテンツ。
リストテーブルロールでテーブルを構築する場合、テーブルセル内に出現する項目の一部が 79 文字の制限を超える場合があります。文字数制限に影響を与えずに、この大規模なコンテンツをテーブルで再現する方法はありますか？
:orphan: ロールと参照。
ファイルの先頭に :orphan: ロールがあるファイル (toc ツリーに含まれていない) は、別のファイルから :ref: ロールを使用してファイルにリンクしてもリンクされません。このリンクの問題を解決する方法はありますか？
Pandoc 変換の問題。
Pandoc でファイルを変換する場合、.xml ファイル内のエントリの一部は正確に変換されません。手順のタイトルとサブセクションのタイトルは正しく解析されず、変換されたドキュメントから削除されます。Pandoc は手順番号も削除します。現在の解決策は、完全な .rst ファイルをビルドされた .xml バージョンと比較し、見出し、サブ見出し、および手順番号が正しいことを確認し、元のファイルと一致することを確認することです。これは議論できる問題でもあります。
- 解決できない RST の問題に関する連絡先
- 作成者: David Goodger
- 連絡先: docutils-develop@lists.sourceforge.net
移行方法
注: tox を使用したくない場合は、ローカルにこれらをインストールしてください: pip install sphinx; pip install openstackdocstheme そして conf.py を含むディレクトリに移動し、sphinx-build /path/to/source/ path/to/build/ を実行してデフォルトで html 出力を取得します。
Sphinx ビルドには依存関係のある要件があるため、仮想環境で作業するのが最適です。幸いなことに、openstack-manuals プロジェクトには tox が設定されているため、必要な依存関係を含む仮想環境を作成できます。Mac または Ubuntu マシンで Python と pip がインストールされている場合は、これを行います。
- openstack-manuals リポジトリをクローンします。
- openstack-manuals ディレクトリに変更します。
- これを実行します
-
tox -e py27
-
- おめでとうございますというメッセージが表示されたら、これを実行します
Mac/Ubuntu
source .tox/py27/bin/activate
Windows
source .tox/py27/Scripts/activate
プロンプトの先頭に (py27) が表示されるはずです。
これで、必要な前提条件がすべてインストールされ、追加の tox コマンドを実行できます。コマンドのリストを表示または編集するには、openstack-manuals ディレクトリの tox.ini を表示または編集します。RST ドキュメントをビルドするには、
tox -e docs
これにより、sphinx-build doc/playground-user-guide/source/ doc/playground-user-guide/build/html が実行されます。
ビルドが完了したら、doc/playground-user-guide/build/html/index.html を開いて結果の出力を表示できます。
Oxygen を使用した移行
- Oxygen で DocBook ブックファイルを開きます。
- ドキュメント > 変換 > 変換シナリオの構成を選択します。
- DocBook XHTML - Chunk を選択します。
- 関連付けられたものを適用 (1) をクリックします。
- /out/xhtml-chunks/ ディレクトリに生成された中で、次のスクリプトを実行します
-
- for i in *.xhtml
- do
- # Convert from XHTML to RST
- file_name=${i%.*l}.rst
- pandoc -s -t rst $i -o $file_name
- sed -i -e '4,16d' $file_name
- sed -i -e '/+--------------------------+$/,$d' $file_name
- sed -i -e '$d' $file_name
- sed -i -e '$d' $file_name
- # Rename file to second line of new RST content, but lowercase and all non-alphanumeric chars renamed to underscores:
- real_file_name=$(sed 's/[^a-zA-Z0-9\-]/_/g;2q;d' $file_name | awk '{print tolower($0)}').rst
- mv $file_name $real_file_name<pre><nowiki>
- # Replace all cross-refs to xhtml files to renamed rst files:
- sed -i '' -e "s/\<$i/fixmefixmefixme/g" *.rst
- # sed -i '' -e "s/\ fixmefixmefixme.*\`__//g" *.rst
- done
-
- fixmefixmefixme が出力されている場所をクリーンアップします。これは、相互参照が存在しなくなったことを示します。
- pandoc 変換で段落として出力されたテーブルをクリーンアップします。
- Example タイトルと Table タイトルから番号を削除します。
- chapter_ ファイルの名前を変更し、ファイルの内容と一致するようにタイトルを付けてください。例: "Networking API 2.0 Overview" を "networking-api-2.0-overview" にします。
- .. code:: 行から "programlisting" "screen" および "literallayout" を削除します。
- 変換パッチをコミットする場合は、関連するブループリントをコミットメッセージに含めます。例:
-
- Convert ch_compute_focus.xml to RST
- Implements: blueprint archguide-mitaka-rst
-
テキストエディタを使用した移行
- pandoc をインストールします。
- openstack-manuals master ブランチを更新し、ブランチを作成します。
- pandoc コマンドを実行して、.xml ファイルを .rst に変換します。例:
-
pandoc -f docbook -t rst -s ch_compute_focus.xml -o compute-focus.rst
-
- 変換されたファイルを <guide>/source フォルダに移動します。
- 変換された RST ファイルの名前を変更し、ファイルの内容と一致するようにタイトルを付けてください。例: "Networking API 2.0 Overview" を "networking-api-2.0-overview" にします。
- Pandoc には癖があるため、すべてのコンテンツがソースファイルから移行されていることを確認してください。
- テキストエディタを使用して、次のタスクを完了します
- pandoc 変換で段落として出力されたテーブルをクリーンアップします。
- Example タイトルと Table タイトルから番号を削除します。
- .. code:: 行から "programlisting" "screen" および "literallayout" を削除します。
- 変換された RST ファイルが OpenStack Documentation Contributor Guide で説明されている規則に従っていることを確認します
- ガイドをローカルにビルドして、エラーがないことを確認します
-
tox -e docs
-
- 変更をコミットし、コミットメッセージに関連するブループリントを含めます。例:
-
- Convert ch_compute_focus.xml to RST
- Implements: blueprint archguide-mitaka-rst
-
ドキュメント移行計画
Mitaka リリースでは、構成リファレンスガイドとアーキテクチャ設計ガイドを移行しました。詳細については、詳細な仕様を参照してください。
API リファレンス計画
https://docs.openstack.org/contributor-guide/api-guides.html を参照して、プロセスの説明を確認してください。Anne はすでにファイルを事前処理しているため、この Wiki ページの他の移行手順はまったく必要ありません。
以下のサービスにサインアップし、このパッチからファイルをダウンロードしてください: https://review.openstack.org/#/c/311596/。これらは手動で多くのクリーンアップが必要ですが、ツールが可能な限り進めます。また、https://review.openstack.org/312184 のようなデータを公開するジョブを設定します。
操作指南
章にサインアップし、他の人がレビューできるように doc/ops-guide/source に RST を使用してパッチを作成します。貢献は大歓迎です。コミットメッセージに "Implements: blueprint ops-guide-rst" を追加してください。
O'Reilly 規則に従って、この本が作成されていることを確認してください。
| 章/セクション (古いファイル名) | 章/セクション (新しいファイル名) | 姓名 | パッチ URL | 状态 |
|---|---|---|---|---|
| bk_ops_guide.xml | ||||
| preface_ops.xml | preface_ops.rst | venkatamahesh | https://review.openstack.org/#/c/292071 | マージ済み |
| part_architecture.xml | part_architecture.rst | venkatamahesh | https://review.openstack.org/#/c/292064 | マージ済み |
| part_operations.xml | operations.rst | KATO Tomoyuki | https://review.openstack.org/#/c/291987/ | マージ済み |
| ch_arch_cloud_controller.xml | ch_arch_cloud_controller.rst | venkatamahesh | https://review.openstack.org/#/c/292061 | マージ済み |
| ch_arch_compute_nodes.xml | ch_arch_compute_nodes.rst | venkatamahesh | https://review.openstack.org/#/c/292059 | マージ済み |
| ch_arch_examples.xml | ch_arch_examples.rst | venkatamahesh | https://review.openstack.org/#/c/292052 | マージ済み |
| section_arch_example-neutron.xml | section_arch_example-neutron.rst | venkatamahesh | https://review.openstack.org/#/c/291965 | マージ済み |
| section_arch_example-nova.xml | section_arch_example-nova.rst | venkatamahesh | https://review.openstack.org/#/c/291783 | マージ済み |
| ch_arch_network_design.xml | ch_arch_network_design.rst | venkatamahesh | https://review.openstack.org/#/c/291974 | マージ済み |
| ch_arch_provision.xml | ch_arch_provision.rst | venkatamahesh | https://review.openstack.org/#/c/291976 | マージ済み |
| ch_arch_scaling.xml | ch_arch_scaling.rst | venkatamahesh | https://review.openstack.org/#/c/291978 | マージ済み |
| ch_arch_storage.xml | ch_arch_storage.rst | venkatamahesh | https://review.openstack.org/#/c/292007 | マージ済み |
| ch_ops_advanced_configuration.xml | ch_ops_advanced_configuration.rst | venkatamahesh | https://review.openstack.org/#/c/292008 | マージ済み |
| ch_ops_backup_recovery.xml | ch_ops_backup_recovery.rst | venkatamahesh | https://review.openstack.org/#/c/292011 | マージ済み |
| ch_ops_customize.xml | ch_ops_customize.rst | venkatamahesh | https://review.openstack.org/#/c/292013 | マージ済み |
| ch_ops_lay_of_land.xml | lay_of_the_land.rst | KATO Tomoyuki | https://review.openstack.org/#/c/291996/ | マージ済み |
| ch_ops_log_monitor.xml | ch_ops_log_monitor.rst | venkatamahesh | https://review.openstack.org/#/c/292015 | マージ済み |
| ch_ops_maintenance.xml | ch_ops_maintenance.rst | venkatamahesh | https://review.openstack.org/#/c/292022 | マージ済み |
| ch_ops_network_troubleshooting.xml | ch_ops_network_troubleshooting.rst | venkatamahesh | https://review.openstack.org/#/c/292027 | マージ済み |
| ch_ops_projects_users.xml | projects_users.rst | KATO Tomoyuki | https://review.openstack.org/#/c/292002/ | マージ済み |
| ch_ops_resources.xml | ch_ops_resources.rst | venkatamahesh | https://review.openstack.org/#/c/292033 | マージ済み |
| ch_ops_upgrades.xml | ch_ops_upgrades.rst | venkatamahesh | https://review.openstack.org/#/c/292035 | マージ済み |
| ch_ops_upstream.xml | ch_ops_upstream.rst | venkatamahesh | https://review.openstack.org/#/c/292036 | マージ済み |
| ch_ops_user_facing.xml | ch_ops_user_facing.rst | venkatamahesh | https://review.openstack.org/#/c/292050 | マージ済み |
完成转换为 RST 格式
在审查完草稿指南并认为准备好发布后，我们需要执行以下步骤：
- 创建一个补丁，包含以下步骤（例如，请参阅 https://review.openstack.org/#/c/248577/ 或 https://review.openstack.org/211766）
- 删除旧指南，这里是 security-guide
- 将 RST 指南移动到新指南的位置（security-guide-rst -> security-guide）。
- 更新 tools/build-all-rst.sh 以反映此更改
- 从 doc/pom.xml 中删除条目
- 更新 RELEASENOTES.rst
- 如果仓库中没有其他 DocBook 指南，请更新 tox.ini
- 更新 doc-tools-check-languages.conf
- 将本地化文件重命名为新的目录名称
- 如果存在“.tx/config”文件，请更新它（删除 RST 指南并更新路径）
- 如果仓库中没有其他 DocBook 指南
- 从 Jenkins 中删除任务。例如：https://review.openstack.org/211843
- 清理 tox.ini。例如：https://review.openstack.org/212127
- 删除 tools/generatepot。例如：https://review.openstack.org/212129
- 更新 .gitignore。例如：https://review.openstack.org/212685
- 如果仓库不是 openstack-manuals 仓库，请停止同步 XML 文件：https://review.openstack.org/211842 并在该补丁合并后删除复制的文件：https://review.openstack.org/211904
- 修复 docs.openstack.org 和其他指南中的链接：https://review.openstack.org/212044
- 从 content 目录创建重定向到顶级 index.html 文件
- 更新所有链接，使其指向新指南（security-guide，而不是 security-guide/content）
- 删除指向指南 PDF 的链接
- 将旧指南的翻译与新指南同步（需要 Andreas 在 Transifex 中完成）
- 告知 i18n 团队转换已完成，以及哪个资源处于活动状态。
- 从 docs.openstack.org 中删除旧指南和草稿 RST 指南（需要 docs.openstack.org 管理员权限）
- 在所有更改完成后重新生成 sitemap.xml：https://review.openstack.org/212689 并将更改列入黑名单：https://review.openstack.org/212690
