はじめに

プロジェクトのドキュメントをマークダウンを使って、フロー図やUML図も書いてさらにホスティングしたいけど、クラウド（github pagesとかgitlab pages）は使えない、でも認証くらいはかけたいって思った時に、Django+MkDocsでそういったものが簡単に作れないかなと思ったのがきっかけです。（実用性があるかは不明ですが）

MkDocsについて

MkDocsは、プロジェクトドキュメントをマークダウン形式で書ける高機能な静的サイト生成プログラムです。Pythonで作成されていてpipでインストールします。テーマも用意されていて、ReadtheDoc風にもできます。

前提

今回は、Django2系で構築します。

作成

Djangoプロジェクトを作成

# プロジェクトを作成
django-admin startproject django_mkdocs

# docsアプリケーションを作成
python manage.py startapp docs

# MkDocsをビルドしたHTML等の静的ファイルを格納するディレクトリを作成
mkdir docs/static

作成したdocsアプリケーションをsetting.pyに登録します。

･･･
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'docs',
]
･･･

MkDocsのインストール

MkDocsは以下のコマンドを入力することで、プロジェクトを
新規作成できます

# 例
mkdocs new (プロジェクト名)

今回は、mkdocsというプロジェクトを作成しようと思うので

mkdocs new mkdocs

と、Djangoプロジェクト上で入力します。
すると、以下のようなファイルが生成されていると思います。

mkdocs
├docs
│  └index.md :　プロジェクトドキュメント
└ mkdocs.yml　　:　configファイル

次に、MkDocsがきちんと動作するか確認するために
ドキュメントサーバーを起動します。

cd mkdocs
mkdocs serve

・・・
[I 180929 22:49:17 server:292] Serving on http://127.0.0.1:8000
[I 180929 22:49:17 handlers:59] Start watching changes
[I 180929 22:49:17 handlers:61] Start detecting changes
[I 180929 22:49:21 handlers:132] Browser Connected: http://127.0.0.1:8000/

と表示されて、ローカル上で問題なくMkDocsが起動しました。

特にこのままでも問題ないのですが、yml直下でコマンドを打たないと
いけないため、ymlの場所と、ドキュメント(index.md)の場所を変えます。

mv mkdocs/mkdocs.yml .
mv mkdocs/docs/index.md mkdocs/
rm -r mkdocs/docs

このままだと、MkDocsが動作しないためmkdocs.ymlを書き換えます。

key	内容
site_name	サイト名
theme	テーマ
docs_dir	マークダウンファイルを格納するディレクトリ
site_dir	ビルドされたHTMLファイル等を格納するディレクトリ

今回は以下のように設定します。

site_name: Django + MkDocs Site

docs_dir: 'mkdocs'
site_dir: 'docs/static/docs'

この後で、以下のコマンドを入力し、MkDocsをビルドしてみます。

mkdocs build

docs/static/docs以下にビルドファイルが作成されれば大丈夫です。　

MkDocsのコマンドやymlについては、公式サイトを参照ください。
https://www.mkdocs.org

Docsアプリケーションを作成

django_mkdocs

"""
django_mkdocs/urls.py
"""

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('docs/', include('docs.urls')),
]

docsアプリケーションへincludeを追加します。
（アプリケーション毎にurls.pyを定義する方がいいというベストプラクティスに習って）

"""
settings.py
"""
･･･
TIME_ZONE = 'Asia/Tokyo'
･･･
# MkDocsのディレクトリ
DOCS_DIR = os.path.join(BASE_DIR, 'docs/static/docs')
DOCS_STATIC_NAMESPACE = os.path.basename(DOCS_DIR)

settings.pyについてタイムゾーンを変更し、
MkDocsディレクトリのstatic_namespaceを定義します。
※ LANGUAGE_CODEは特に変更してません。

認証アプリケーションを追加

accountsアプリケーションを作成

python manage.py startapp accounts

認証を追加

Djangoの認証機能を使用

Djangoには標準でログイン・ログアウト機能がありますので、それを使いたいと思います。

カスタムUserモデルを作成

Djangoには標準で認証機能があり、Userモデルを持っているのですが、
そのまま使用すると、後から変えようと思うと大変（らしい）なので、
そのまま継承したカスタムしてないカスタムUserモデルを定義します。

authのUserモデルをそのままコピーして、


･･･
class User(AbstractBaseUser, PermissionsMixin):
･･･
　　　　　　　　# is_mkdocsを追加（TrueのユーザだけMkDocsを表示させる）
    is_mkdocs = models.BooleanField(
        _('MkDocs User'),
        default=False,
        help_text=_('the user can use MkDocs site.'),
    )

    class Meta:
        verbose_name = _('user')
        verbose_name_plural = _('users')
        # 抽象モデル設定をコメント化
        # abstract=True
･･･

というモデルを追加して、

Setting.pyに、認証用モデルを

AUTH_USER_MODEL = 'accounts.User'

を追加します。
その後で、

django manage.py makemigrations
django manage.py migrate

でマイグレーションすると、、カスタムユーザテーブルが作成されます。

ログイン、ログアウト画面を作成する

単純にログインやログアウトをさせるためには、urls.pyのURLパターンに

path('accounts/', include('django.contrib.auth.urls')),

を追加すれば良いですが、自分でカスタマイズする場合は

path('accounts/', include('accounts.urls')),
path('accounts/', include('django.contrib.auth.urls')),

として、accountsのurls.pyやviews.pyなどを追加すれば良いです。
あと以下の設定をSettings.pyに追記しておきます。

LOGIN_URL = '/accounts/login'
LOGIN_REDIRECT_URL = '/docs/'
LOGOUT_REDIRECT_URL = '/accounts/login/'

その後で、http://127.0.0.1:8000/docs/
にアクセスすれば、ログインとログアウト機能付きのMkDocsの完成です。

ソースコードは以下に置いています。
https://github.com/Taka710/mkdocs_django

参考

以下のサイトを参考にさせていただきました。
https://www.hacksoft.io/blog/integrating-a-password-protected-mkdocs-in-django/
https://qiita.com/NAKKA-K/items/7627b6a22f364941b989
https://it-engineer-lab.com/archives/544