プログラムを中心とした個人的なメモ用のブログです。
タイトルは迷走中。
内容の保証はできませんのであしからずご了承ください。
Sphinx には only ディレクティブというのがあり、これを使用することで出力フォーマットに応じて処理を分けることができます。
これを使用し、以下のように出力フォーマットに応じて処理を分けてみます。
Sphinx のコードは以下のようになります。
.. only:: html .. image:: img/01.svg .. only:: latex .. image:: img/01.png .. image:: img/01_001.png .. image:: img/01_002.png
うーん、面倒ですね。
他にも AutoImage という拡張もあるのですが、出力フォーマットに応じて読み込む画像を変えるということはできなさそうでした。
PlantUML にはプリプロセッサの機能があり、C言語と同じように定数定義や ifdef などが使用できます。
これを使用し、以下のように出力フォーマットに応じて処理を分けてみます。
PlantUML のコード上では、以下のように定義します。
!define _PROJECT_NAME_ ProjectName
また、コマンドライン引数でも定数は定義できます。
> plantuml.jar -DPNG="png" hoge.puml
-D が定数定義するオプションで、その後に続く文字が定義する文字列です。
つまり、上記は以下の定義と同じ意味です。
!define PNG "png"
これで、上記のようにコマンドライン引数で定数を定義しつつ、PlantUML 内のコードに以下のように記述すれば、PNG で出力するときのみ画像が分割されることになります。
!ifdef PNG newpage !endif
Sphinx でドキュメントを作成する際、テーマを設定することができます。
デフォルトで用意されているテーマは一応全て試してみましたが、どれも気に入りませんでした。
なので、私はいつも Read the Docs のテーマ (sphinx_rtd_theme) を使用しています。
しかし、sphinx_rtd_theme にも気に入らない点がいくつかあります。
見出しのレベルによる違いが文字の大きさだけなので、どこが見出しの境目なのか分かりづらいと思います。
ちなみに Docker のドキュメントも sphinx_rtd_theme を使用していますが、こちらはカスタマイズされているようで、見出しにアンダーラインが引かれています。
これは分かりやすくなっていて良いと思います。
レスポンシブ対応のためか、sphinx_rtd_theme は PC のブラウザで閲覧したときに横幅が MAX まで広がりません。
PC でしか閲覧しないなら横幅 MAX まで広げたいところです。
レスポンシブ対応のためか、テーブルでセル内の文字数が多い場合に自動改行されず、横スクロールバーが表示されてしまいます。
こちらも PC でしか閲覧しないなら折り返して全体を表示してほしいところです。
これは sphinx_rtd_theme ではなく Sphinx の仕様ですが、テーブル作成時に widths 属性を設定しなかった場合、各カラムは等幅になります。
HTML 作成後に CSS を上書きするようにしてやります。
以下のような内容で _static/css/my_theme.css を作成します。
@import url("theme.css");
.wy-nav-content {
max-width: none;
}
h1,h2,h3,h4,h5,h6 {
border-bottom: 1px solid #ccc;
}
.wy-table-responsive table td, .wy-table-responsive table th {
white-space: normal;
}
colgroup {
display: none;
}
conf.py に以下の設定を追加します。
html_style = "css/my_theme.css"
以上で完了です。
C# で GitHub の特定のプロジェクトのリリースバージョンを取得するコードを書いてみました。
HTML は HtmlAgilityPack を使用してパースしています。
GitHub Gist ではソースコードのインデントをスペースにするかタブにするか、スペースの場合は何マス分かを設定できます。
しかし、エディタ上のソースコードを貼り付けた後で Indent mode と Indent size を変更して保存しても、もとのタブ幅に戻ってしまいます。
これ検索しても対処方法が全く見つからなかったのですが、皆さん困っていないのでしょうか?
それともコードスニペットにコードをコピーしてくるのが間違っているのでしょうか?
とりあえず試行錯誤の結果、解決方法が見つかったので載せておきます。
例として、エディタ上はインデントがタブのものを、GitHub Gist ではスペース4つ分に置き換えます。
これできちんとインデントの設定が反映されます。
ドキュメントを書いていると「詳細は以下を参照してください」という表現は多々必要になってくると思います。
これを英語で書くとするならば、とりあえずは以下のような感じですかね。
following ではなく below を使う表現もあるようです。
C# の命名規則に従ってプログラムを書いていると、クラス名とプロパティ名が同じになることが多いと思います。
例えばこんな感じです。
public Hoge Hoge { get; set; } = new Hoge();
これ、私はエラーになると思い込んでいたのですが、普通にコンパイル通るみたいです。
ちょっと驚きでした。
しかし、例外がありまして、クラス Hoge が内部クラスの場合はエラーになります。
つまり、プロパティ Hoge が定義されているクラスの内部でクラス Hoge が定義されている場合です。
この場合はどうすればいいんでしょかね。