canonicalwebteam.discourse

CanonicalWebteam.discourse

Расширение колбы для интеграции дискурсивного контента, сгенерированного документам на ваш сайт. Этот проект был ранее назван discourse_docs .

Написание документации

Документация о том, как написать страницы документации в дискурсе для потребления этим модулем и как настроить веб -сайт для использования модуля, можно найти в каноническом дискурсе.

Пример шаблона колбы для страниц документации можно найти в папке 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. Для получения дополнительной информации следуйте этому руководству (только внутреннее).

Запуск тестов, личинка и форматирования

Тесты можно запускать с 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 . Вам также нужен индексный идентификатор темы, который вы можете получить от discourse.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 будет вашим представлением для списка страниц Engage, которые вы можете получить, используя метод EngagagePages(args).get_index()
• В то время как single_engage_page будет вашим представлением на страницах единого взаимодействия, которое вы можете получить, используя EngagePages(args).get_engage_page(path)

Точно так же для поглощений вам просто нужно передать page_type="takeovers" .

• Чтобы получить список поглощений EngagePages(args).get_index() также.
• Чтобы получить список активных поглощений EngagePages(args).parse_active_takeovers() .

Страница

• get_index предоставляет два дополнительных аргументов limit и offset , чтобы обеспечить функциональность страниц. Они по умолчанию до 50 и 0 соответственно.
• Если вы хотите получить все страницы Engage, которые в случае некоторых сайтов, таких как jp.ubuntu.com, не так много, вы можете пройти limit=-1
• Используйте MaxLimitError в exceptions.py , чтобы справиться с чрезмерным лимитом. По умолчанию, это вынесет ошибку, когда превзойдет 500