canonicalwebteam.discourse

CanonicalWebtam.Discourse

Flask -Erweiterung, um Diskursinhalte in DOCs in Ihre Website zu integrieren. Dieses Projekt wurde zuvor discourse_docs ausgezeichnet.

Schreibdokumentation

Dokumentation zum Schreiben von Dokumentationsseiten im Diskurs für den Verbrauch durch dieses Modul und die Konfiguration der Website für das Modul finden Sie im kanonischen Diskurs.

Beispielflächenvorlage für Dokumentationsseiten finden Sie in examples . Weitere Informationen finden Sie im Readme in diesem Ordner.

Installieren

Installieren Sie das Projekt mit PIP: pip install canonicalwebteam.discourse

Sie können die Erweiterung Ihres Projekts wie folgt hinzufügen, um zumindest base_url und index_topic_id durch Ihre eigenen Einstellungen zu ersetzen:

 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 )

Sobald dies hinzugefügt wird, müssen Sie Ihrem Vorlagenordner das document.html hinzufügen.

Lokale Entwicklung

Für die lokale Entwicklung ist es am besten, dieses Modul mit einem unserer Website -Projekte wie Ubuntu.com zu testen. Für weitere Informationen folgen Sie diesem Handbuch (nur intern).

Ausführen von Tests, Leinen und Formatieren

Tests können mit Tox durchgeführt werden:

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

Anweisungen zur Erweiterung der Seiten einbeziehen

Da Sie sich ein geschütztes Thema ansehen, müssen Sie api_key und api_username angeben. Sie benötigen auch eine Index -Themen -ID, die Sie von Discourse.ubuntu.com erhalten können. Ihr Indexthema muss einen Metadatenbereich enthalten. Besuchen Sie den EngageParser, um weitere Informationen zur Struktur zu erhalten. Sie werden ermutigt, einen Entwurfsnamen zu verwenden, der nicht mit existierenden Blaupausen kollidiert. Die Vorlagen müssen mit den in den angegebenen Parametern angegebenen übereinstimmen.

Hier ist ein Beispiel für eine Implementierung:

 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 Ihrem Projekt müssen Sie Ihre eigenen Ansichten erstellen:

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

• Wobei build_engage_index Ihre Ansicht für die Liste der Einbindungsseiten ist, die Sie mit der Methode EngagagePages(args).get_index() erhalten können.
• Während single_engage_page Ihre einzelne Ansicht für Engageseiten, die Sie mit EngagePages(args).get_engage_page(path) erhalten können

Ähnlich für Übernahmen müssen Sie nur page_type="takeovers" passieren.

• Um eine Liste von Takeovers EngagePages(args).get_index() .
• Um eine Liste der aktiven Übernahmen zu erhalten EngagePages(args).parse_active_takeovers() .

Pagination

• get_index bietet zwei zusätzliche Argumente limit und offset , um Paginationsfunktionen bereitzustellen. Sie standardmäßig 50 bzw. 0.
• Wenn Sie alle Seiten einbeziehen möchten, die bei einigen Websites wie jp.ubuntu.com nicht so viele sind, können Sie limit=-1 übergeben
• Verwenden Sie MaxLimitError in den exceptions.py . Standardmäßig wird ein Fehler angezeigt, wenn es 500 übertrifft