我可以使用 Sphinx 在 django 项目中编写我的帮助文档吗答案

【问题标题】：Can I use Sphinx write my help documentation in a django project我可以使用 Sphinx 在 django 项目中编写我的帮助文档吗
【发布时间】：2019-11-24 17:53:42
【问题描述】：

我有一个 django 项目，其中一个菜单选项是“帮助”。帮助文档是使用 Sphinx 编写的，有很多页面，例如索引、简介、第一个视图、用户、词汇表。

我已经用过html了：

<li><a href="help" target="_blank">Help</a></li>

我的网址和浏览量是：

urls.py

urlpatterns = [
                url(r'^help/', views.index, name='index'),
              ]

views.py：

def index(request):
    url = 'help/index.html'
    return render(request, url, {})

这会将我从菜单转到帮助索引页面，但是我在文档页面中单击的每个链接都会通过视图中的索引重新路由我，并重新显示索引页面，而不是显示我的链接请求。

如果直接在浏览器中显示索引页面，而不使用 django 站点，它会按预期工作。

我不愿意将帮助子系统集成到 django 中，因为每次我“制作 html”时它都会被覆盖。

我应该采取什么方法？

【问题讨论】：

Sphinx 生成一个静态网站，旨在直接提供给用户。所以我想你应该检查如何配置 Django 来做到这一点，也许是 docs.djangoproject.com/en/2.2/howto/static-files ？
@Tekins 谢谢。我认为这或多或少是我在回答中得出的结论

标签： django python-sphinx

【解决方案1】：

我正在使用的一种折衷方案是在 urls.py 中为帮助文档中的每个页面创建一个条目，并在 view.py 中创建一个相应条目，因此

urls.py

urlpatterns = [
                url(r'^help/first_view', views.first_view, name='first_view'),
                url(r'^help/glossary', views.glossary, name='glossary'),
                url(r'^help/', views.index, name='index'),
              ]

views.py

def index(request):
    url = 'help/index.html'
    return render(request, url, {})


def first_view(request):
    url = 'help/first_view.html'
    return render(request, url, {})


def glossary(request):
    url = 'help/glossary.html'
    return render(request, url, {})

我已经编写了一个脚本来更新'make html'之后的html页面以指向相关的css和图像文件。就我而言，我的 css 文件位于 static/css 中，我执行以下功能：

CSS_POINTER = '{% load static %}'

for line in file_lines:   
    if '.css' in line:
        middle = line.replace('_static', "{% static 'css")
        line = middle.replace('.css', '.css'+"' %}")

if not CSS_POINTER in file.lines:
    file_lines.insert(0, CSS_POINTER)

【讨论】：