Skip to main content

Flask extension to integrate discourse content generated to docs to your website.

Project description

canonicalwebteam.discourse

Flask extension to integrate discourse content generated to docs to your website. This project was previously named discourse_docs.

Writing documentation

Documentation for how to write documentation pages in Discourse for consumption by this module and how to configure the website to use the module can be found in the Canonical discourse.

Example Flask template for documentation pages can be found in examples folder. Please refer to the README in that folder for more information.

Install

Install the project with pip: pip install canonicalwebteam.discourse

You can add the extension on your project as follows, replacing, at least, base_url and index_topic_id with your own settings:

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)

Once this is added you will need to add the file document.html to your template folder.

Local development

For local development, it's best to test this module with one of our website projects like ubuntu.com. For more information, follow this guide (internal only).

Running tests, linting and formatting

Tests can be run with 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

Instructions for Engage pages extension

Because you are viewing a protected topic, you must provide api_key and api_username. You also need an index topic id, which you can get from discourse.ubuntu.com. Your index topic must contain a metadata section. Visit the EngageParser for more information about the structure. You are encouraged to use an blueprint name that does not collide with existent blueprints. The templates must match the ones provided in the parameters indicated.

Here is an example of an implementation:

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
)

In your project, you need to create your own views:

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)
)
  • Where build_engage_index would be your view for the list of engage pages, which you can get by using the method EngagagePages(args).get_index()
  • While single_engage_page would be your single engage pages view, which you can get using EngagePages(args).get_engage_page(path)

Similarly for takeovers, you just need to pass page_type="takeovers".

  • To get a list of takeovers EngagePages(args).get_index() also.
  • To get a list of active takeovers EngagePages(args).parse_active_takeovers().

Pagination

  • get_index provides two additional arguments limit and offset, to provide pagination functionality. They default to 50 and 0 respectively.
  • If you want to get all engage pages, which in the case of some sites like jp.ubuntu.com there are not that many, you can pass limit=-1
  • Use MaxLimitError in the exceptions.py to handle excessive limit. By default, it will raise an error when it surpasses 500

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

canonicalwebteam_discourse-6.3.0.tar.gz (34.5 kB view details)

Uploaded Source

Built Distribution

canonicalwebteam_discourse-6.3.0-py3-none-any.whl (39.7 kB view details)

Uploaded Python 3

File details

Details for the file canonicalwebteam_discourse-6.3.0.tar.gz.

File metadata

File hashes

Hashes for canonicalwebteam_discourse-6.3.0.tar.gz
Algorithm Hash digest
SHA256 023ff63f9fab62bf1f038c112dcb316eeac92191f7a6ff5790d525585ce86782
MD5 529a335d388a2aeb1d1f274141ce3cc7
BLAKE2b-256 64efab91845c046c15bf7d4e03e9e71abe67297c53810f6212bd9c7edfbc4e50

See more details on using hashes here.

File details

Details for the file canonicalwebteam_discourse-6.3.0-py3-none-any.whl.

File metadata

File hashes

Hashes for canonicalwebteam_discourse-6.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 fb793ca783d2da2b1c48b5e25e76c7bcc33a658db43bed031dc4ab1214366f66
MD5 2f0905957de67a5a9c931e45b452795c
BLAKE2b-256 ffd96dc3434a741ef803184ddf35a027d636b6c6d2300efb41c90fa2ea53b3aa

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page