在 Django 项目的 URL 中托管使用 mkdocs 生成的 API 文档答案

【问题标题】：Hosting API docs generated with mkdocs at a URL within a Django project在 Django 项目的 URL 中托管使用 mkdocs 生成的 API 文档
【发布时间】：2015-09-10 21:05:59
【问题描述】：

我倾向于在 Markdown 中编写我的 API 文档并使用 MkDocs 生成一个静态站点。但是，我想托管文档的站点是 Django 站点。所以我的问题是，我似乎无法通过谷歌搜索找到答案，我将如何在 /api/v1/docs 这样的位置托管 MkDocs 静态生成的站点文件并在该 URL 上查看静态站点？

更新： 我应该指出我确实在 Apache 下提供所有静态文件，并且不使用 runserver 或调试模式来提供静态文件，这太疯狂了。该网站是完全构建的，并且与 REST API 一起使用。

我的问题只是我如何让 Django（或者我应该说 Apache）在某个 URL 下为 MkDocs 生成的静态站点（对于我的 API 文档）提供服务。我了解如何为网站提供媒体和静态文件，但不一定了解如何提供 MkDocs 生成的内容。它会生成一个完全静态的“站点”目录，其中包含 HTML 和资产文件。

【问题讨论】：

我是个白痴。我想到了。虽然我总是在生产期间使用 Apache 提供我的静态（媒体和静态）文件，但在我开发时我使用 runserver。 Joran 的评论为我指明了正确的方向，让 MkDocs 生成的站点文件在我开发时（在调试模式下）在 URL 上提供服务。我将 MkDocs 所在的目录添加到我的虚拟主机中，当我使用 Apache 运行它时一切都很好（当然还有Debug = False）。

标签： python django mkdocs

【解决方案1】：

Django 只是一个框架，您需要托管静态文件并使用 Nginx 或 Apache 等工具为它们提供服务。

【讨论】：

是的，但是如果 OP 想在生产中使用静态文件，最佳实践建议上面。
我同意我正要输入那个......但谁知道他是如何为他的网站提供服务的（可能是 apache :( 或者可能是 runserver）

【解决方案2】：

我认为您需要 apache 中的 alias 指令，并使用它将某些 URL 重定向到您的静态文档站点。

【讨论】：

是的，这就是我最终想通的（我是个白痴），不要再将其视为 Django 在特定 URL 上为网站的生成文档部分提供服务，而不是在现实中（在生产）Apache 将在 URL 处提供静态站点的目录。

【解决方案3】：

来自文档

urls = [
    static(settings.STATIC_URL, document_root=settings.STATIC_ROOT),
    ("/home","views.home"),
    ...

 ]

https://docs.djangoproject.com/en/1.8/howto/static-files/#serving-static-files-during-development

在您的请求中，您将更改为

 static("/api/v0/docs",document_root="/home/docs/")

【讨论】：

我会在这里注意到“这不适合生产使用”，如文档中所述。 docs.djangoproject.com/en/1.8/howto/static-files/deployment
是的，好点...您的建议是正确的，因为他应该通过 apache 或 nginx 提供静态文件