discourse-docsify

Flask扩展，从discourse论坛帖子中获取数据，以创建docsify（文档）网站。

这允许您利用docsify的功能，同时仍然受益于discourse的论坛特性：任何人都可以在您的社区中扩展和贡献美观的文档。

该项目受到了这个canonicalwebeteam的repo的启发。

设置

使用以下方法安装

pip install discourse-docsify

您可以直接初始化扩展

from flask import Flask
from discourse_docsify import Docs

app = Flask(__name__)
# for more config options and additional parameters see below
docs = Docs(app, config={
    'DOCS_HOMEPAGE_TITLE': 'My Documentation Website',
    'DOCS_DISCOURSE_API_USERNAME': '...',
    'DOCS_DISCOURSE_API_KEY': '...',
    'DOCS_DISCOURSE_BASE_URL': '...',
    'DOCS_DISCOURSE_INDEX_TOPIC_ID': '...',
})

或通过以下操作

from flask import Flask
from discourse_docsify import Docs

# for more config options and additional parameters see below
docs = Docs(config={
    'DOCS_HOMEPAGE_TITLE': 'My Documentation Website',
    'DOCS_DISCOURSE_API_USERNAME': '...',
    'DOCS_DISCOURSE_API_KEY': '...',
    'DOCS_DISCOURSE_BASE_URL': '...',
    'DOCS_DISCOURSE_INDEX_TOPIC_ID': '...',
})

app = Flask(__name__)
docs.init_app(app)

不需要在discourse上安装插件，您只需一个有效的API密钥。

索引主题

索引主题包含主页内容、将文档路径转换为论坛主题的URL映射列表以及文档侧边栏。

在这个主题中，#标题指定了一个节的开头。上述所有内容都对应于一个特定的节。以下是主题应具有的格式

# Homepage
Welcome to my Documentation!
        
# URLs
[details=Mapping table]
| topic | path |
| -- | -- |
| forum-url/t/general-handbook/5258 | /general-handbook |
| forum-url/t/how-to-install/5256  | /installation |
| forum-url/t/developer-api-specs/5259 | /api |
[/details]

# Navigation
[details=Navigation]
| level | path | navlink |
| -- | -- | -- |
| 1 |  | Handbooks |
| 2 | general-handbook | General Handbook |
| 1 | installation | Installation Instructions |
| 1 | api | Dev API |

[/details]

节的名字很重要（Homepage、URLs和Navigation）。

在URL表中，我们有topic（论坛链接）和path（文档URL路径）的配对。

在导航表中，level设置了侧边栏的缩进（意味着级别2的项将位于紧接其上的级别1项内），path是URL表中的路径（或为空，如果您想要一个无链接的分类）和navlink是侧边栏导航项的实际文本。

功能和描述

Discourse-Docsify将在/docs URL前缀（可以通过配置更改）处创建一个蓝图，该蓝图将服务由docsify请求的文件，并通过获取与每个路径关联的主题的论坛内容来实现。

使用原始主题Markdown（而不是discourse生成的HTML输出），因此您可以使用任何docsify兼容的Markdown。

还包括一个缓存功能来加快加载时间（因为每次请求都要查询论坛可能会非常慢），这可以通过简单的Python字典或通过redis实现。

可选地，可以将一个在内容提供之前要运行的功能传递给Docs对象。

pre_content函数

Docs接受第三个参数：pre_content函数，这是一个在每次文档请求之前运行的功能，你可以用它来，例如，基于某种身份验证来限制访问。

def docs_auth_validation(path):
    if 'profile' not in session:
        return redirect('/login')
    if not session['profile']['admin']:
        return abort(403, 'Only admins may view this page.')

docs = Docs(app, {...}, docs_auth_validation)

此函数有一个参数：当前请求的路径。

配置参考