用Django和MkDocs轻松构建文档网站

2 年 ago
科, 雅
2 minutes

首先

使用Markdown编写项目文档，并绘制流程图和UML图，并希望进行托管，但不能使用云服务（如github pages或gitlab pages），但却希望能够添加身份验证，这就是我思考使用Django+MkDocs来实现这些功能的原因。（是否实用尚不清楚）

关于MkDocs

MkDocs是一个功能强大的静态网站生成程序，允许用Markdown格式编写项目文档。它是用Python开发的，可以通过pip进行安装。还提供了多种主题，可以实现类似于ReadtheDoc的效果。

前提 – 提前的条件或假设，用以推断或讨论其他事情。

这次我们将使用Django 2系进行搭建。

制作

创建 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

bannerAds