canonicalwebteam.discourse

canonicalwebteam.discourse

Extensión Flask para integrar el contenido del discurso generado en los documentos en su sitio web. Este proyecto fue nombrado previamente discourse_docs .

Documentación de escritura

La documentación sobre cómo escribir páginas de documentación en el discurso para el consumo de este módulo y cómo configurar el sitio web para usar el módulo se puede encontrar en el discurso canónico.

Ejemplo de plantilla de frasco para páginas de documentación se puede encontrar en la carpeta examples . Consulte el ReadMe en esa carpeta para obtener más información.

Instalar

Instale el proyecto con PIP: pip install canonicalwebteam.discourse

Puede agregar la extensión en su proyecto de la siguiente manera, reemplazando, al menos, base_url y index_topic_id con su propia configuración:

 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 )

Una vez que se agregue esto, deberá agregar el archivo document.html a su carpeta de plantilla.

Desarrollo local

Para el desarrollo local, es mejor probar este módulo con uno de nuestros proyectos de sitios web como Ubuntu.com. Para obtener más información, siga esta guía (solo interna).

Ejecución de pruebas, pelusas y formateo

Las pruebas se pueden ejecutar con 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 

Instrucciones para la extensión de las páginas Engage

Debido a que está viendo un tema protegido, debe proporcionar api_key y api_username . También necesita una ID de tema índice, que puede obtener de discurso.ubuntu.com. Su tema de índice debe contener una sección de metadatos. Visite el EngageParser para obtener más información sobre la estructura. Se le recomienda que use un nombre de plano que no choca con los planos existentes. Las plantillas deben coincidir con las proporcionadas en los parámetros indicados.

Aquí hay un ejemplo de implementación:

 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
)

En su proyecto, debe crear sus propias vistas:

 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 )
)

• Donde build_engage_index sería su opinión para la lista de páginas de Engage, que puede obtener utilizando el método EngagagePages(args).get_index()
• Mientras que single_engage_page sería su vista de páginas de Engage Single, que puede obtener utilizando EngagePages(args).get_engage_page(path)

Del mismo modo para adquisiciones, solo necesita pasar page_type="takeovers" .

• Para obtener una lista de adquisiciones EngagePages(args).get_index() también.
• Para obtener una lista de adquisiciones activas EngagePages(args).parse_active_takeovers() .

Paginación

• get_index proporciona dos argumentos adicionales limit y offset , para proporcionar funcionalidad de paginación. Defieren a 50 y 0 respectivamente.
• Si desea obtener todas las páginas Engage, que en el caso de algunos sitios como jp.ubuntu.com no hay tantos, puede aprobar limit=-1
• Use MaxLimitError en exceptions.py para manejar el límite excesivo. Por defecto, aumentará un error cuando supera los 500