docs: リンク切れと構成変更に追従していない参照の解消

Kanato Konorequested to merge
chikasuiro/frontistr_documents:feature/fix-broken-links into main

概要

docs/ 配下のリンク切れを網羅的に検出し，参照先を修正した． mkdocs build --clean の WARNING を 18 件から 0 件にする．

Closes #32 (closed)

変更内容

コミットは誤りの性質ごとに分割してある．

1. 相対パスの階層ずれ・綴り誤りの修正（13 リンク / 7 ファイル）

ファイル 修正前 修正後
build_guide/gpu_build.ja.md ../execution_guide/index.ja.md ../execution_guide/overview/01_flow.ja.md
coding_guide/01_element_taxonomy.{ja,en}.md 09_element_advanced.* 他 3 件 ../theory/discretization/…
coding_guide/01_element_taxonomy.{ja,en}.md ../../functions_reference/02_element.* ../functions_reference/…
execution_guide/tutorial_01/01_overview.ja.md ../functions_reference/… 2 件 ../../functions_reference/…
functions_reference/10_partition.ja.md part/partiton.ja.md 2 件 part/partition.ja.md（綴り誤り）
theory/solution_methods/06_geometric_bc.{ja,en}.md 04_external_force_and_assembly.* ../discretization/04_external_force_and_assembly.*

2. 分割された章への参照の張り替え（4 リンク）

governing/01_continuum_mechanics は 01a_kinematics / 01b_stress_balance / 01c_virtual_work / 01d_incremental_analysis に分割済みのため，リンク元の文脈に 対応する後継章へ振り直した．リンクラベルも新しいページタイトルに合わせている．

  • notation/01_tensor_notation.ja → 01b_stress_balance（同じ関連項目リストに 01a・01c が既出）
  • constitutive/01_linear_elastic.ja → 01a_kinematics（変形勾配・ひずみ）
  • appendix_static_linear.ja → 01a_kinematics（有限変形の一般論）
  • governing/01c_virtual_work.en → 01d_incremental_analysis（01a・01b は既出）

3. 画像リンクの修正（5 リンク）

mkdocs build の WARNING には現れないため，別途パスの実在を走査して検出した．

  • examples/tutorial_02.{ja,en} — ミーゼス応力の図が「画像が見つからない」として コメントアウトされていた．FrontISTR_manual からの移行時に漏れていた tutorial02_02.png を追加し，セクション相対パス（image/）で復帰させた
  • execution_guide/overview/01_flow.en → analysis01_01.en.png（言語別画像）
  • keyword_reference/cnt/orientation.{ja,en} → analysis05_02.{ja,en}.png（同上）

4. 日本語見出しアンカーの有効化とアンカーリンクの修正

mkdocs.yml の toc に slugify を設定し，日本語見出しがそのままアンカー ID に なるようにした．これにより無効だったアンカーリンク 7 件が解決する．

  - toc:
      permalink: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower

併せて，従来の自動生成 ID に依存していた 3 リンクを見出し名ベースに書き換えた．

  • functions_reference/02_element.ja — #_8 → #オーバーラップ深さ
  • functions_reference/10_partition.ja — #1341 → #四面体1次要素341
  • build_guide/gpu_build.ja — #gpu → #gpu-を用いたビルド

影響範囲の注意 この設定変更により，公開サイトの見出しアンカー URL が全ページで変わる． 外部から #_2 形式の URL でブックマーク・被リンクされている場合は無効になる．

5. 欠落していた英語版ページの追加

keyword_reference/cnt/write_visual.ja.md には英語版が無く，英語ビルドでは i18n の フォールバックにより日本語ページが配信されるため，その visualization/visual.ja.md リンクが解決していなかった．同じく英語版が欠けていた write_result.ja.md と併せて 英語版ページを追加した．

FrontISTR_manual における両ファイルの記述内容は貧弱だったため，欠損ファイルを新規作成 するにあたっては，旧マニュアルの文面をそのまま転記するのではなく，日本語版を基に記述も 作り直している．

6. Scope / Memo メタ情報内の古い章参照の更新（9 ファイル / 15 行）

Scope / Memo は改版時の検証に使うメタ情報であり，「〜を参照」「〜へ委ねる」という 前方参照が実在しない章を指したままでは役割を果たさない．参照先が現存しないものを 後継章に更新した．

  • discretization/02_element_formulations → discretization/08_element_solid
  • governing/01_continuum_mechanics → governing/01a_kinematics
  • solution_methods/01_static_nonlinear / 01d_newton_raphson / 01b_total_lagrange / 01c_updated_lagrange → solution_methods/01_newton_raphson・01b_convergence
  • solution_methods/01a_incremental_framework → governing/01d_incremental_analysis
  • discretization/01_weak_form_and_fem → 01_shape_functions・05_numerical_integration・ 04_external_force_and_assembly

「旧 material/01_material.ja.md から移植」「移植元: …」のように，内容の由来を記録した 記述は経緯の記録として意図的に残している．

7. 同階層リンクの冗長な接頭辞の除去（4 リンク）

06_geometric_bc が solution_methods/ へ移動した際に残った ../solution_methods/ を 除去し，他ページと同じくファイル名のみの参照に揃えた．

8. 言語サフィックスなしのリンクの修正（10 リンク / 5 章）

examples/ の 5 章が，姉妹章を tutorial_NN.md の形で参照していた．i18n プラグインが ビルド時に解決するため公開サイト上では正しく動作するが，その名前のファイルはリポジトリに 存在しないため，Markdown を直接読む経路（リポジトリブラウザ・エディタのプレビュー・ ローカルの Markdown ツール）ではリンクが切れている．CONTRIBUTING.md「相互参照」でも 言語サフィックス付きの記法を定めている．

  • examples/tutorial_05 / tutorial_07 / tutorial_08（ja/en）→ tutorial_03.{ja,en}.md
  • examples/tutorial_13（ja/en）→ tutorial_12.{ja,en}.md
  • examples/tutorial_15（ja/en）→ tutorial_04.{ja,en}.md

公開サイトへの影響は無い．日本語ビルド・英語ビルドのいずれでも，生成される リンク先は従来どおり tutorial_NN.html である．

検証方法と結果

mkdocs.yml の複製に validation.links を追加した一時設定でビルドし， .md リンク・アンカー・未認識リンクをすべて WARNING として検出させた （一時設定ファイルはコミットしていない）．

validation:
  links:
    anchors: warn
    absolute_links: warn
    unrecognized_links: warn
検証 修正前 修正後
mkdocs build --clean WARNING 18 件 0 件
同（上記 validation 付き） WARNING 25 件 0 件
python3 tools/check_style.py 0 errors, 32 warnings 0 errors, 32 warnings（増減なし）
画像リンクの実在（357 件走査） 欠損 5 件 欠損 0 件
DeprecationWarning — 0 件

check_style.py の 32 件の warning は，メタ情報コメント欠落など本 MR と無関係な既存分であり， 着手時から増減していない．

レビューにあたって

  • 「2. 分割された章への参照の張り替え」は，分割前の 1 ページに対して後継が複数あるため， リンク元の文脈からの判断が入っている．振り先が意図と合っているかご確認いただきたい．
  • 「4. 日本語見出しアンカーの有効化」は mkdocs.yml の挙動変更であり，公開サイトの アンカー URL が変わる．採否のご判断をいただきたい．
Edited by Kanato Kono

Merge request reports