Discourse module guide

We host different kinds of documentations on both ubuntu.com and canonical.com including but not limited to:

All of these are pulled from Discourse using our canonicalwebteam.discourse module.

This module can be used to fetch content from either an index topic, or by utilizing a data explorer query, which is a Discourse plugin. More about both of these approaches later in the article.

Setting up the Discourse module

First, include the module in your flask based project’s requirements.txt:

canonicalwebteam.discourse==6.0.0 #replace 6.0.0 with the most recent version

Second, you need to set up Discourse API:

from canonicalwebteam.discourse import DiscourseAPI

discourse_api = DiscourseAPI(
    base_url="<base_url>",
    session=session,
    api_key=<DISCOURSE_API_KEY>,
    api_username=<DISCOURSE_API_USERNAME>,
    get_topics_query_id=<data_explorer_query_id>,
)

base_url - where ever you’re pulling the docs from. For example, https://discourse.ubuntu.com - Required

session - current session of flask application - Required

DISCOURSE_API_KEY - API key for the discourse account - Optional but required for accessing locked/private content.

DISCOURSE_API_USERNAME - Username for the discourse account - Optional but required for accessing locked/private content.

data_explorer_query_id - id of data explorer query that pulls the desired data from Discourse. For example, this query is responsible for fetching all the topics - Optional but required if you are not pulling data from a topic index page.

For instructions on how to run this module locally in sync with a repo (for example, ubuntu.com), please check it out here

More about Data Explorer Query

We use Discourse Data Explorer plugin to run queries on our forum’s database. By passing the ID of these queries to our discourse module, it fetches the data as described by the SQL within that query from Discourse forum.
For example, this query fetches all the topic matching a provided set of params. You can play around with the query in playground provided by this plugin as well as modify the parameters to see how it affects the query result. These params can be passed directly to the relevant module (Tutorials, EngagePages, Category etc.).
If you don’t have permissions to view data explorer queries, please reach out to Britney or Sites Devs.

Examples

Let’s have a look at how different documentations are set up on ubuntu.com and canonical.com

Tutorials - ubuntu.com/tutorials

from canonicalwebteam.discourse import (
    TutorialParser,
    Tutorials,
    DiscourseAPI,
)

discourse_api = DiscourseAPI(
    base_url="https://discourse.ubuntu.com/",
    session=session,
    api_key=DISCOURSE_API_KEY,
    api_username=DISCOURSE_API_USERNAME,
    get_topics_query_id=2,
)

Tutorials(
    parser=TutorialParser(
        api=discourse_api,
        index_topic_id=13611,
        url_prefix=tutorials_path,
    ),
    document_template="/tutorials/tutorial.html",
    url_prefix="/tutorials",
    blueprint_name="tutorials",
).init_app(app)

The index_topic_id is the number that appears after the slug in Discourse topic’s URL. For example, the topic URL for tutorials topic is https://discourse.ubuntu.com/t/about-the-tutorials-category/13611, so the index_topic_id is 13611.

When you provide an index_topic_id, that topic will be used to generate the content and navigation on the page. The document_template defines how the page should look like, but the content is actually pulled from the topics listed within the index topic. That means the data explorer query will be irrelevant in this scenario.

Engage pages - ubuntu.com/engage

The data explorer query that fetches all the engage pages from Discourse is located at https://discourse.ubuntu.com/admin/plugins/explorer?id=14, so the get_topics_query_id passed when initializing discourse API is set to 14.

from canonicalwebteam.discourse import (
    DiscourseAPI,
    EngagePages,
)


engage_pages_discourse_api = DiscourseAPI(
    base_url="https://discourse.ubuntu.com/",
    session=get_requests_session(),
    get_topics_query_id=14,
    api_key=DISCOURSE_API_KEY,
    api_username=DISCOURSE_API_USERNAME,
)

case_study_path = "/case-study"

case_studies = EngagePages(
    api=engage_pages_discourse_api,
    category_id=51,
    page_type="engage-pages",
    exclude_topics=[17229, 18033, 17250],
)

Case studies - canonical.com/case-study

The data explorer query that fetches all the engage pages from Discourse is located at https://discourse.ubuntu.com/admin/plugins/explorer?id=14, so the get_topics_query_id passed when initializing discourse API is set to 14.

from canonicalwebteam.discourse import (
    DiscourseAPI,
    EngagePages,
)


engage_pages_discourse_api = DiscourseAPI(
    base_url="https://discourse.ubuntu.com/",
    session=get_requests_session(),
    get_topics_query_id=14,
    api_key=DISCOURSE_API_KEY,
    api_username=DISCOURSE_API_USERNAME,
)

case_study_path = "/case-study"

case_studies = EngagePages(
    api=engage_pages_discourse_api,
    category_id=51,
    page_type="engage-pages",
    exclude_topics=[17229, 18033, 17250],
)

Technical Docs - canonical.com/microstack/docs

This utilizes topic index page rather than data explorer query to fetch documentation.

from canonicalwebteam.discourse import (
    DiscourseAPI,
    Docs,
    DocParser,
)


microstack_docs = Docs(
    parser=DocParser(
        api=DiscourseAPI(
            base_url="https://discourse.ubuntu.com/",
            session=search_session,
        ),
        index_topic_id=18212,
        url_prefix="/microstack/docs",
    ),
    document_template="/microstack/docs/document.html",
    url_prefix="/microstack/docs",
    blueprint_name="microstack_docs",
).init_app(app)

Note: To find a topic by a given ID, you can go the relevant discourse and append /t<id> to the URL. For example, to find the topic by ID 18212, you can go to https://discourse.ubuntu.com/t/18212 which would redirect you to https://discourse.ubuntu.com/t/microstack-documentation/18212

Bonus: Learn more about how to create your own documentation and display from a discourse topic here.

Relevant Topics:

Last updated 16 days ago.

Help improve this document in the forum.