canonicalwebteam.discourse

canonicalwebteam.discourse

生成されたドキュメントに生成された談話コンテンツをWebサイトに統合するためのFlask拡張。このプロジェクトは以前にdiscourse_docsという名前が付けられていました。

文書を書く

このモジュールによる消費のための談話でドキュメントページを書く方法のドキュメントと、モジュールを使用するようにWebサイトを構成する方法は、標準的な談話に記載されています。

ドキュメントページの例のフラスコテンプレートは、 examplesフォルダーにあります。詳細については、そのフォルダーのREADMEを参照してください。

インストール

PIPでプロジェクトをインストールします： pip install canonicalwebteam.discourse

プロジェクトの拡張機能を次のように追加して、少なくともbase_urlとindex_topic_id独自の設定に置き換えることができます。

 import talisker . requests
from canonicalwebteam . discourse import DiscourseAPI , Tutorials , TutorialParser

app = Flask ( "myapp" )
session = talisker . requests . get_session ()

discourse = Tutorials (
    parser = TutorialParser (
        api = DiscourseAPI (
            base_url = "https://forum.example.com/" , session = session
        ),
        index_topic_id = 321 ,
        url_prefix = "/docs" ,
    ),
    document_template = "docs/document.html" ,
    url_prefix = "/docs" ,
)
discourse . init_app ( app )

これが追加されたら、ファイルdocument.htmlテンプレートフォルダーに追加する必要があります。

ローカル開発

ローカル開発のために、ubuntu.comのようなウェブサイトプロジェクトの1つでこのモジュールをテストするのが最善です。詳細については、このガイド（内部のみ）をフォローしてください。

実行中のテスト、糸くず、フォーマット

TOXでテストを実行できます。

pip3 install tox  # Install tox
tox               # Run tests
tox -e lint       # Check the format of Python code
tox -e format     # Reformat the Python code 

エンゲージページ拡張機能の指示

保護されたトピックを表示しているため、 api_keyとapi_username提供する必要があります。また、IndexトピックIDが必要です。これは、dismy.ubuntu.comから入手できます。インデックストピックにはメタデータセクションが含まれている必要があります。構造の詳細については、EngageParserをご覧ください。既存の青写真と衝突しない青写真名を使用することをお勧めします。示されているパラメーターで提供されるテンプレートと一致する必要があります。

実装の例は次のとおりです。

 engage_pages = EngagePages (
    api = DiscourseAPI (
        base_url = "https://discourse.ubuntu.com/" ,
        session = session ,
        get_topics_query_id = 14 ,
        api_key = DISCOURSE_API_KEY , # replace with your API key
        api_username = DISCOURSE_API_USERNAME , # replace with correspoding username
    ),
    category_id = 51 ,
    page_type = "engage-pages" , # one of ["engage-pages", "takeovers"]
    exclude_topics = [] # this is a list of topic ids that we want to exclude from Markdown error checks
    additional_metadata_validation = [] # list of additional keys in the metadata table that you want to validate existence for e.g. language
)

あなたのプロジェクトでは、あなた自身の意見を作成する必要があります：

 app . add_url_rule (
    "/engage" , view_func = build_engage_index ( engage_pages )
)

app . add_url_rule (
    "/engage/<path>" , view_func = single_engage_page ( engage_pages )
)

• build_engage_index 、メソッドEngagagePages(args).get_index()を使用して取得できるエンゲージページのリストのビューとなります。
• single_engage_pageシングルエンゲージページビューであり、 EngagePages(args).get_engage_page(path)を使用することができます

同様に、テイクオーバーの場合、 page_type="takeovers"を渡すだけです。

• Takeovers EngagePages(args).get_index()のリストを取得するには。
• アクティブな買収EngagePages(args).parse_active_takeovers()のリストを取得するには。

ページネーション

• get_index 、ページネーション機能を提供するために、2つの追加の引数limitとoffset提供します。それぞれデフォルトで50と0になります。
• jp.ubuntu.comのようないくつかのサイトの場合、それほど多くはない場合、すべてのエンゲージページを取得したい場合は、 limit=-1を渡すことができます
• exceptions.pyでMaxLimitErrorを使用して、過度の制限を処理するためにPSYを使用します。デフォルトでは、500を超えるとエラーが発生します