MKDOCSを使用した製品のドキュメントを構築します

「製品はそのドキュメントと同じくらい良い」という一般的な格言があります。これは、物理製品と同じようにソフトウェアにも当てはまります。 フロントエンドのデザインを専門としていない小さなインディー開発者として、私はしばしばフリーランサーを雇って製品Webサイトを構築します。これには、通常、ドキュメントセクションが含まれています。

ドキュメントセクションでは、単純な製品であっても、構築するのにかなりの時間とお金がかかることがあるため、すべてのサイトでホイールを再発明する必要がないのはいいことです。幸いなことに、方法があります

キーテイクアウト

mkdocsは、プロジェクトのドキュメントを構築するのに最適な無料の静的サイトジェネレーターです。軽量で、ホストが簡単で、スタンドアロンのサイトまたはより大きなサイトのドキュメントセクションに使用できます。 MKDOCを使用するには、PythonとPIP（Pythonパッケージマネージャー）をコンピューターにインストールする必要があります。 MKDOCSはコンピューターにローカルにインストールされているため、オフラインでドキュメントを作成できます。

mkdocsでは、さまざまなテーマとmkdocs.yml構成ファイルを介して新しいページを追加する機能を備えたカスタマイズを可能にします。また、ドキュメントのローカルプレビュー用の組み込みWebサーバーも含まれています。 MKDOCSで構築されたドキュメントは、GitHubページやドキュメントなどのサービス、または独自のサーバーで無料でホストできます。 MKDOCSは、これらのプラットフォームへの展開も直接サポートしています

• mkdocsの導入
• MKDOCSは、プロジェクトのドキュメントの構築に向けた無料の静的サイトジェネレーターです。スタンドアロンのサイト、またはより大きなサイトのドキュメントセクションのみを生成するために使用できます。
mkdocsは静的ファイルを生成するため、ドキュメントは軽量でホストが簡単です。これは、Githubページやドキュメントの読み取りなどの無料サービスを使用するか、もちろん独自のサーバーで。 この記事では、MKDOCSを紹介し、インストール方法を示し、ドキュメントを作成し、最終的にWebサーバーで生成されたドキュメントをホストします。 MKDOCSが生成するドキュメントの種類の感覚を取得するには、Docsテーマを読むMKDOCSで構築された私のProfilEpress WordPressプラグインドキュメントをご覧ください。
• mkdocsはPythonで書かれています。ドキュメントソースファイルはマークダウンで記述され、単一のYAML構成ファイルで構成されています。
mkdocsを使用してドキュメントを作成するには、コンピューターにローカルにインストールする必要があります。次に、それをインストールする方法を次に見てみましょう pythonとmkdocsのインストール
• Jekyll（主にブログに使用され、Rubyで構築された）やMKDOCなどの静的サイトジェネレーターは、コマンドラインチョップが必要なので、注意してください。ただし、コマンドラインの操作に慣れていない人にとっては、見た目ほど悪くないので、読んで試してみることをお勧めします！pythonとpipのインストール

  MKDOCSをインストールするには、コンピューターにPythonとPIP（Pythonパッケージマネージャー）をインストールする必要があります。彼らはすでにあなたのコンピューターにインストールされているかもしれません。 Python 3.4以降がインストールされている場合は、おそらくPIPがインストールされています。 （完全な指示については、Pythonインストールガイドを参照してください。）

  ubuntuなどのLinuxディストリビューションにPythonをインストールするには、このStackoverFlowスレッドを参照するか、分布のGoogle検索を実行します。

  Windowsの場合は、希望するバージョンインストーラーをダウンロードし、ファイルを実行してPythonをインストールします。

  代わりに、マシンにチョコレートパッケージマネージャーをインストールしている場合は、Pythonをインストールしてください。

  Python DistributionがPIPがインストールされていることを確認するには、PIP -versionコマンドを実行します。それ以外の場合は、python get-pip.pyまたはchocoインストールパイプを介してパイプをインストールしてインストールします。 mkdocsのインストール

  PythonとPIPがインストールされたので、MKDOCSをインストールするためにMKDOCをインストールするPIPを実行してください。

  すべてが問題ないことを確認するには、mkdocsを実行するのに役立ちます。mkdocsコマンドを試してみてください。

  Windowsにいて、MKDOCSコマンドが生きていない場合は、パス環境変数にC：Path-to-Python-folderscriptsを必ず追加してください。

  ドキュメントの構築
  PythonとMKDOCSが設定されたので、実際のドキュメントを作成できます。
  まず、ドキュメントのプロジェクトを作成し（SP-DOCと呼びましょう）、作成されたフォルダーに移動します：

  生成されたプロジェクトフォルダーには、ドキュメントのマークダウンファイルが保存されるDocsフォルダーと、構成ファイルmkdocs.yml。

  ここにディレクトリ構造があります：

  次の裸の最小構成をmkdocs.ymlファイルに追加します：

$ mkdocs new sp-doc
$ cd sp-doc

mkdocsは、「mkdocs」、「docsを読む」、「ブートストラップ」など、いくつかのテーマを備えています。デフォルトのテーマを使用するつもりであるとします。その場合、上記のコードでreadthedocsをmkdocsに置き換えるだけです。

ページ構成は、ドキュメントとナビゲーションメニューのために構築する必要があるページのセットを決定するために使用されます。 ページに追加されたマークダウンファイルは、Docsフォルダーに関連している必要があります。たとえば、docsディレクトリ内にconfigsという新しいフォルダーを作成し、setup.mdファイルを追加した場合、mkdocs.ymlファイル構成のページにページに追加する方法は次のとおりです。

これにより、ドキュメントメニューに自動的に表示される新しいページが作成されます。まず、start.mdページがあり、タイトル「get start」があります。

|-- docs              # MD doc pages
    |-- index.md
|-- mkdocs.yml        # config file

また、「構成」と呼ばれるドキュメントメニューに新しいセクションを追加しました。このセットアップとデバッグページへのリンクがあります。

mkdocsには組み込みのWebサーバーが含まれているため、作業中にドキュメントをローカルにプレビューできます。

Webサーバーを起動するには、mkdocs.yml configファイルが存在するディレクトリにあることを確認し、mkdocs serveコマンドを実行します。

ブラウザのhttp://127.0.0.1:8000にアクセスして、ドキュメントを表示します：

作成したものに満足している場合は、MKDOCSビルドを実行して、サイトディレクトリに保存されるドキュメントの静的ファイルを生成します。

静的ファイルをコピーして、ドキュメントをライブで選択するために選択したWebサーバーでホストできます。

次のセクションでは、MKDOCSを展開してドキュメントとGitHubページを読む方法を学びます。 mkdocsの展開

まず、GitHub（またはBitbucket）リポジトリを作成してファイルを保存します。

次のコマンドを実行して、https://github.com/collizo4sky/sitepoint_mkdocsは私自身のmkdocsリポジトリであるGithubに展開します。

ドキュメントファイルを展開して、無料のドキュメントサービスであるドキュメントを読み取りましょう。

docs

を読んでください

最初に、アカウントがない場合はアカウントを作成してログインします。

$ mkdocs new sp-doc
$ cd sp-doc

[プロジェクト]ボタンのインポートをクリックするか、[プロジェクトメニューの追加]項目をクリックします。

GitHubまたはBitBucketアカウントを接続してドキュメントを読み取ってプロジェクト全体をインポートすることを選択できます。代わりに、手動でインポートするプロジェクトボタンをクリックして、手動インポートを使用します。

下の画像に示すように、フォームに記入してください：

githubからドキュメントを正常にインポートすると、プロジェクトページにリダイレクトされます：

http://sitepoint-doc.readthedocs.org/en/latest/。で生成されたドキュメントを表示できます

サブドメインのドキュメントが必要な場合は、プロジェクトのサブドメインにDNSのCNAMEレコードを指してください。 たとえば、ドキュメントをdocs.sitepoint.comで利用できるようにするには、SitePoint-doc.readthedocs.orgを指すcnameレコードを作成します。

githubページ

次に、別の無料ホスティングサービスであるGitHubページでドキュメントをホストする方法を見てみましょう。

GITリポジトリの作業ブランチにいることを確認してください。これが私たちの場合のマスターブランチです。

コマンドmkdocs gh-deploy-clean

を実行します

舞台裏では、このコマンドはドキュメントを構築し、GH-Pagesブランチにコミットし、ブランチをGitHubに押し込みます。

ここにgithubページにあるSitePointドキュメントのデモがあります。

その他のプロバイダー

静的ファイルを提供できるホスティングプロバイダーは、MKDOCSによって生成されたドキュメントを提供するために使用できます。次のガイドラインは、いくつかの一般的な支援を提供する必要があります

MKDOCSビルドコマンドを使用してサイトを構築すると、すべてのファイルは、MKDOCS.YAML設定ファイルのSite_DIR構成オプション（デフォルトは「サイト」にデフォルト）に割り当てられたディレクトリに書き込まれます。

そのディレクトリの内容をホスティングプロバイダーのサーバーのルートディレクトリにコピーするだけで、完了します。または、ドキュメントがサイトのサブセクションである場合は、ファイルを指定されたサブフォルダーに移動します。

要約

このチュートリアルでは、Python静的WebサイトジェネレーターであるMKDOCSを使用してドキュメントを作成する方法、およびGitHubページで無料でドキュメントを展開およびホストする方法を学び、ドキュメントを読む方法を学びました。

以前にmkdocsを使用したことがありますか？そうでない場合は、それを使用することを検討しますか？現在、ユーザーにドキュメントを提供することをどのように扱っていますか？あなたのフィードバックを聞いたり、あなたが持っているかもしれない質問に答えたいです。 MKDOCSを使用した製品のドキュメントの構築に関するよくある質問（FAQ）

mkdocsを使用するための前提条件は何ですか？

mkdocsを使用するには、システムにPythonをインストールする必要があります。 MKDOCSは、Pythonバージョン2.7、3.5、3.6、3.7、3.8、およびPypyをサポートしています。 Python -version in Your Commandプロンプトを入力して、Pythonバージョンを確認できます。 Pythonが正常にインストールされている場合、バージョン番号が表示されます。そうでない場合は、最初にPythonをインストールする必要があります。 Pythonがインストールされた後、PythonパッケージインストーラーであるPIPを使用してMKDOCSをインストールできます。 PIPを入力するコマンドプロンプトにMKDOCSをインストールしてMKDOCSをインストールします。

MKDOCSサイトの外観をカスタマイズするにはどうすればよいですか？デフォルトのテーマは「mkdocs」と呼ばれますが、他にも多くのテーマがあります。 mkdocs.yml構成ファイルを編集して、テーマを変更できます。テーマセクションでは、MKDOCSを目的のテーマの名前に置き換えます。一部のテーマでは、カスタムCSSまたはJavaScriptファイルを追加することでさらにカスタマイズすることもできます。 Docsディレクトリにファイル。ファイルの名前は、ページのURLとして使用されます。次に、mkdocs.yml構成ファイルのページセクションに新しいエントリを追加します。フォーマットは - [「ページタイトル」、「filename.md」]です。ページのタイトルは、ナビゲーションメニューのリンクテキストとして使用されます。

mkdocsサイトを展開するにはどうすればよいですか？

mkdocsには、githubページの組み込み展開コマンドが含まれています。コマンドプロンプトからmkdocs gh-deployを実行するだけで、Mkdocsはサイトを構築し、GithubリポジトリのGH-Pagesブランチにプッシュします。別のプロバイダーに展開する場合は、MKDOCSビルドでサイトを構築し、サイトファイルを手動でアップロードする必要があります。

ドキュメントを読むことでmkdocsを使用できますか？

はい、mkdocsは人気のあるドキュメントホスティングプラットフォームであるDocsの読み取りと完全に互換性があります。ドキュメントを読むMKDOCを使用するには、リポジトリのルートで.readthedocs.yml構成ファイルを作成し、ドキュメントタイプとしてmkdocsを指定する必要があります。 > PIPインストールを実行してMKDOCSを更新できます - コマンドプロンプトでMKDOCをアップグレードします。これにより、MKDOCSの最新バージョンをダウンロードしてインストールします。

プライベートドキュメントにMKDOCを使用できますか？ただし、組み込みのgithubページの展開を使用している場合、ドキュメントは公開されます。ドキュメントをプライベートに保つ必要がある場合は、パスワード保護またはアクセス制御をサポートする別のホスティングプロバイダーを使用できます。テーマには、組み込みの検索機能が含まれます。テーマに検索が含まれていない場合、または別の検索プロバイダーを使用する場合は、検索プラグインをmkdocs.yml構成ファイルに追加できます。ドキュメントは？

mkdocsは、PDFSではなくHTML Webサイトを生成するように設計されています。ただし、MKDOCSサイトをPDFに変換できるサードパーティのツールとサービスがあります。 mkdocs.yml構成ファイルのページセクションから。ページセクションの各エントリは、ナビゲーションメニューのリンクになります。リンクの順序は、ページセクションのエントリの順序と一致します。

以上がMKDOCSを使用した製品のドキュメントを構築しますの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。