Windows10にSphinxを導入してみました!

Windows10にSphinxを導入してみました!

こんにちは、トリック(kaz)です。

今回は、技術系の記事に挑戦します。
勉強のためにも、残しておきたいと思い書きます!
光栄にも手順をたどってご自分のPCで導入してくださる方は、
手順をしっかり検討したうえで自己責任でお願いいたします。。。

本題です。
最近、仕事でドキュメント整備について任されていまして、
ほぼ再構築的な感じなのですが、、、
ざっくりいうと、

「Excelやパワポで散在したドキュメントをどうにか整備したい。
 整備後にまた、同様のことになると困るので、運用面から変えたい。
…という感じです。

それで、Excelやパワポで管理するのってそもそもどうなのか!?
というところから検討しまして、、、
テキストベースで管理した方が、
 バージョン管理もしやすいし差分も一発でわかるよね?」
「しかも、htmlへの変換も簡単にできるみたいだし、
 PlantUMLやmermaid.jsと併用すれば、
 図だってテキストで表現して書き込めるらしい。。。」
「htmlとかPDFで十分人に見せられる形なら、
 Excelやパワポにこだわらなくていいんじゃないのか?」
という流れになりました。

実際、そういう話は一般的になりつつあるようで、
markdownやasciidoc、reST、Wikiなどの
軽量マークアップ言語を実用しているというネット情報が多いです。
そんな中で、私が目を付けたのはasciidocとreST(Sphinx)です。
それぞれで定められた記述ルールに従ってファイルを作成したら、
それぞれの形式にあったhtmlへの変換ツールを使用して、
記述したファイルをhtmlへ変換します。
asciidocではasciidoctor、reSTではSphinxが挙げられます。
(他にも挙げられるかは要調査です、すみません)

これらのツールはネットでも情報が出てきやすかったので飛びついてしまいました 笑
ただ、「どちらの方がいいのか?」というのが調べてもなかなか分からず、、、
実際に両方入れて確かめてみよう!」という方針になりました。
asciidoctorの方は職場の自分のPCに導入してみましたので、
この記事ではSphinxを導入してみます。
導入には参考にしたwebページがありますので、載せておきます。
「Sphinx執筆環境をWindowsに構築する手順」
(https://qiita.com/terahide/items/253eff6fba38c8f53746)

@terahideさん、ありがとうございます。

参考記事の通り、まずminicondaをインストールしました。
anacondaよりも軽く、sphinx導入という目的上、十分であることを理由に、
minicondaのインストールが推奨されてます。
anacondaは名前ぐらいは知っていましたが、minicondaを私は知らなかったです。
なので、比較情報について検索し、見つけた記事が下記です。
気になった方がいれば、ご一読ください。
(anacondaはlinuxPCを操作するときによくフォルダ名で見ていました。
 決して実在の大蛇を知っているけど…的な事ではありません。笑)
「AnacondaとMinicondaの比較、どちらで環境構築するべきか」
(https://echomist.com/anaconda-vs-miniconda/)

echomisさん、ありがとうございます。

minicondaのインストールですが、一度失敗し、やり直しました。
参考記事の「Minicondaの導入」の6で既存の環境を壊すのが怖くて、
指示とは異なる選択をしました
それで、PATHが設定されていなくて、
「conda」、「Python」のバージョン確認ができませんでした。
PATHに設定するべきパスが分からなくて詰み、指示通りやり直しました。
minicondaはそれで、うまくインストールできました。

気になったので、
結局どこのパスがPATHに設定されているのかな?と思ってみてみました。
下記に環境変数PATHの内容です。関係ないところは一応隠しております。。。
上から5つ追加されてます。
「コントロールパネル」→「システムとセキュリティ」→「システム」→「システムの詳細設定」→「環境変数(N)」でPathを選んで「編集(I)」で確認できました。(最後の「編集」は下側のボタンです。)

PATHの環境変数設定

PATHの環境変数設定

正直、自力ではわからないです。笑

とはいえ、これでminicondaのインストールが終わりました。
いよいよSphinxのインストールです。
コマンドプロンプトで「conda install Sphinx」です。

「conda install Sphinx」を打ち込んでみた!

パーミッション(フォルダやファイルに対する権限)エラーになってしまっている。(失敗した)

失敗してしまいました。
minicondaは管理者権限でインストールされていて、
ユーザ権限では書き込み等が出来ない状態でした。
そこで、問題となっている「C:\ProgramData\Miniconda3」に
ユーザでも書き込み等できるように権限付与します。
(linuxでいう「sudo」コマンドにあたるものを探せばよかったかもしれません。笑)

「C:\Programdata\Miniconda3」はUsersでは「変更」も「書き込み」もできない状態

上の「編集」ボタンを押して、この画面を開いて、
Usersに「変更」と「書き込み」の権限を付与しました。

この状態にして、再度Sphinxのインストールコマンドを打つと。。。

なぜか再描画された?しかしうまくいったようです。

うまくいったようです!ッ……
さて、次は「sphinx-autobuild」プラグインのインストールです。
そこで、今までの流れで、「conda」コマンドを使用してインストールを試みました!

PackagesNotFoundError パッケージが見つからないとのエラー

「sphinx-autobuild」パッケージが見つからない類のエラーが出てしまいました。
失敗したようです。
そこで、参考記事に「または~」の形で記載されていた……
「pip」コマンドを使用してみました。

Successfully!! 「pip」コマンドだとうまくインストールできるようです。

「pip」コマンドだと成功したようです!
「これで、必要なものはすべてそろった!」と考えた私は、
Sphinxの公式ページのチュートリアルを実施します。
最初は、プロジェクト(ひな形)を作成するのが最初のステップですね。

プロジェクト(ひな形)を作成しました。

プロジェクトを作成すると、こんな感じのフォルダがプロジェクトとして出来上がります!

プロジェクトを作成しました。
チュートリアルに従って、ファイルを作成し、編集しました。

index.rstが親ページ、新しく作成した2ファイルが子ページ
となるようなサイトを構成します。

index.rst を編集し、
art_of_community.rst 及び expert_python.rst を作成しました。(手作業です。)
引き続きチュートリアルに従い、次はビルドを行います。(自動ビルドの設定を忘れてました。笑)

「make html」でビルドしてます。

「build」フォルダにhtmlができている!!

ビルドが成功すると、「build」フォルダにhtmlファイルが出来ています。
赤で囲んだ3ファイルがこのサイトのメインとなるページです。
index.html に、
expert_python.html と art_of_community.html へのリンクが貼られています。

Sphinxでビルドしてできたindexページ

上のスクショのページが、Sphinxでビルドしてできた親ページです。
赤で囲んだリンクから下のスクショで示したページに飛べるようになっています。

expert_python.html

art_of_community.html

まとめ

いや~、初めて技術系の内容を執筆してみました。
やったことは、他の記事で紹介されている内容でしたが、
自分なりにやってみて、
ハマってしまったところとその解決方法まで触れられたので、
ある程度、、、
ほんのちょびっとかもしれませんが、
付加価値のある記事が書けたかなと思います。
今後も、形に残すということをモチベーションにして
勉強していけたらいいなと思います。

技術系カテゴリの最新記事