canonicalwebteam.discourse

CanonicalWebTeam.Discourse

Flask Extension untuk mengintegrasikan konten wacana yang dihasilkan ke dokumen ke situs web Anda. Proyek ini sebelumnya dinamai discourse_docs .

Dokumentasi menulis

Dokumentasi untuk bagaimana menulis halaman dokumentasi dalam wacana untuk dikonsumsi oleh modul ini dan cara mengkonfigurasi situs web untuk menggunakan modul dapat ditemukan dalam wacana kanonik.

Contoh template flask untuk halaman dokumentasi dapat ditemukan di folder examples . Silakan merujuk ke readme di folder itu untuk informasi lebih lanjut.

Memasang

Instal proyek dengan PIP: pip install canonicalwebteam.discourse

Anda dapat menambahkan ekstensi pada proyek Anda sebagai berikut, mengganti, setidaknya, base_url dan index_topic_id dengan pengaturan Anda sendiri:

 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 )

Setelah ini ditambahkan, Anda perlu menambahkan dokumen document.html ke folder template Anda.

Pengembangan Lokal

Untuk pengembangan lokal, yang terbaik adalah menguji modul ini dengan salah satu proyek situs web kami seperti ubuntu.com. Untuk informasi lebih lanjut, ikuti panduan ini (hanya internal).

Menjalankan tes, sering dan format

Tes dapat dijalankan dengan 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 

Instruksi untuk melibatkan ekstensi halaman

Karena Anda melihat topik yang dilindungi, Anda harus menyediakan api_key dan api_username . Anda juga memerlukan ID topik indeks, yang bisa Anda dapatkan dari wacana.ubuntu.com. Topik indeks Anda harus berisi bagian metadata. Kunjungi EngageParser untuk informasi lebih lanjut tentang struktur. Anda didorong untuk menggunakan nama cetak biru yang tidak bertabrakan dengan cetak biru yang ada. Templat harus cocok dengan yang disediakan dalam parameter yang ditunjukkan.

Berikut adalah contoh implementasi:

 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
)

Dalam proyek Anda, Anda perlu membuat pandangan Anda sendiri:

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

• Di mana build_engage_index akan menjadi pandangan Anda untuk daftar halaman terlibat, yang bisa Anda dapatkan dengan menggunakan metode EngagagePages(args).get_index()
• Sedangkan single_engage_page akan menjadi tampilan halaman keterlibatan tunggal Anda, yang bisa Anda dapatkan menggunakan EngagePages(args).get_engage_page(path)

Demikian pula untuk pengambilalihan, Anda hanya perlu melewati page_type="takeovers" .

• Untuk mendapatkan daftar pengambilalihan EngagePages(args).get_index() juga.
• Untuk mendapatkan daftar Active Takeovers EngagePages(args).parse_active_takeovers() .

Pagination

• get_index menyediakan dua limit argumen tambahan dan offset , untuk memberikan fungsionalitas pagination. Mereka masing -masing default ke 50 dan 0.
• Jika Anda ingin mendapatkan semua halaman yang terlibat, yang dalam hal beberapa situs seperti jp.ubuntu.com tidak banyak, Anda dapat lulus limit=-1
• Gunakan MaxLimitError di exceptions.py untuk menangani batas yang berlebihan. Secara default, itu akan menimbulkan kesalahan saat melampaui 500