Untuk waktu yang lama, banyak orang telah secara aktif atau aktif menggunakan atau melihat ke arah model penyimpanan dan penerbitan
dokumentasi sebagai kode , ini berarti menerapkan aturan yang sama, alat dan prosedur untuk dokumentasi seperti kode program, misalnya, menyimpannya di repositori, menjalankan tes, menyusun dan melepaskan dalam CI / CD. Pendekatan ini memungkinkan Anda untuk selalu memperbarui dokumentasi dengan kode, versi, dan melacak perubahan menggunakan alat pengembangan yang sudah dikenal.
Namun, pada saat yang sama, banyak perusahaan juga memiliki wiki selama bertahun-tahun, di mana tim dan karyawan lain, misalnya, manajer proyek, memiliki akses ke dokumentasi. Bagaimana jika Anda ingin membawa penyimpanan dan publikasi ke satu tampilan, yaitu, bersama dengan HTML publish dock di Confluence? Pada artikel ini saya akan memberikan gambaran umum tentang solusi untuk tugas penerbitan dokumen dari repositori di Confluence.
Saya telah secara aktif
menggunakan satu solusi untuk waktu yang lama di tim pengembangan antarmuka (bundel RST-Sphinx + sphinxcontribbuilder), dan saya akan menghadirkan yang lain sebagai alternatif, saya akan segera mengatakan bahwa saya belum mencobanya dalam praktik, saya baru saja mempelajari konfigurasi.
Sphinx doc + sphinxcontribbuilder
Sphinx (jangan dikelirukan dengan indeks pencarian dengan nama yang sama) adalah generator dokumentasi yang ditulis dengan Python dan secara aktif digunakan oleh komunitas;
Sphinx bekerja dengan sangat baik di lingkungan lain juga.
Kami tidak akan memikirkan untuk mengaturnya secara terperinci, saya hanya akan membuat reservasi yang di luar kotak dapat menghasilkan HTML statis, man, pdf, dan sejumlah format lain, dan untuk perakitan dan publikasi yang benar dalam repositori harus ada file index.rst (tata letak halaman utama), conf.py (file konfigurasi) dan Makefile (file yang menjelaskan proses pembuatan format, di sini sangat mungkin untuk menjahitnya menjadi buruh pelabuhan dan menjalankan perintah
sphinx-build di sana).
Di luar kotak, Sphinx dapat menghasilkan dermaga dari tata letak * * .rst (RestructuredText) yang ringan, tetapi kami menambahkan kemampuan untuk menulis ke Markdown (rasa CommonMark) untuk pengembang yang lebih nyaman (ekstensi
m2r yang mengubah MD ke RST membantu kami) .
Kami telah menyiapkan seluruh lingkungan untuk Sphinx, dan rakitan dokumentasi dijahit dalam tahap terpisah di
pipa Jenkins, jadi kami melanjutkan dan menggunakan ekstensi
sphinxcontrib.confluencebuilder , yang dapat mengumpulkan dermaga dalam format asli untuk Confluence dan kemudian menerbitkannya. Pertemuan dalam hal ini adalah salah satu format output dokumentasi, bersama dengan HTML.
Agar ini berfungsi, Anda perlu menghubungkan ekstensi di conf.py, di bawah ini adalah fragmen konfigurasi.
extensions = [ 'sphinxcontrib.confluencebuilder', 'm2r' ] templates_path = ['_templates'] source_suffix = ['.rst', '.md'] master_doc = 'index' exclude_patterns = [ u'docs/warning-plate.rst', u'FEATURE.md', u'CHANGELOG.md', u'builder/README.md' ]
Dan kemudian konfigurasikan ekstensi, ia memiliki seperangkat pengaturan:
confluence_publish = True
Poin penting adalah bahwa bahkan jika halaman (sumber dalam .rst) tidak ditentukan dalam toc dan tidak ditambahkan ke exclude_patterns, itu masih akan diterbitkan, tetapi di luar hierarki.
Nama-nama halaman dalam Confluence akan sesuai dengan judul halaman pertama, misalnya, jika Anda memiliki heading Contoh dalam file example.rst, digarisbawahi dengan tanda sama, itu akan menjadi nama halaman dalam Confluence.
Aturan kebersihan, yang cukup jelas, tetapi tetap: buat bot dengan data otorisasi untuk dokumen yang akan Anda terbitkan, mereka dapat ditransfer dalam bentuk variabel lingkungan dalam komposisi buruh pelabuhan, yang digunakan dalam saluran pipa.
Tentu saja ada jebakan. Pertama, tidak semua sintaks RST didukung untuk publikasi dalam Confluence (╯ ° □ °） ╯︵ ┻━┻), ini merepotkan jika Anda ingin mengumpulkan HTML dan Confluence dari satu sumber. Kontainer, arahan daftar tidak didukung, hampir semua atribut arahan, misalnya, menyoroti garis dalam kode blok, penomoran dalam daftar isi, sejajarkan dan lebar untuk daftar tabel.
Daftar apa yang didukung cukup bagus .
Dari yang menyenangkan, termasuk yang didukung, ini memungkinkan Anda untuk menggunakan kembali fragmen konten antara dokumen yang berbeda, autodoc untuk mengumpulkan dokumentasi dari kode, matematika untuk rumus matematika, menggambar tiket dan filter dari jira (untuk ini Anda juga perlu mendaftarkan server Jira dalam konfigurasi), header bernomor dan banyak lagi lain, secara harfiah pada 3 Januari melemparkan
pembaruan besar .
Omong-omong, dukungan Jira muncul di multikonverter Pandoc, mulai dari
versi 2.7.3 Pandoc mendukung markup wiki pertemuan yang sesuai.
Untuk makro dan elemen Confluence yang tidak didukung, ada peretasan yang kotor. RST memiliki arahan
... raw :: , dan ia memiliki atribut pertemuan, ia menerima markup conf, jika Anda benar-benar memerlukan semacam makro - Anda dapat menyalinnya dalam mode edit halaman dalam Confluence (mode kode sumber tersedia oleh ikon <>) dan rekatkan kode "mentah" -nya di sana. Tapi saya tidak mengajari Anda ini.
.. raw:: confluence <ac:structured-macro ac:macro-id="c38bab13-b51e-4129-85ef-737eab8a1c47" ac:name="status" ac:schema-version=^_^quot quot^_^> <ac:parameter ac:name="colour">Green</ac:parameter> <ac:parameter ac:name="title">Is used</ac:parameter> </ac:structured-macro>
Hasilnya adalah sebagai berikut:
Mengapa kita perlu mengonfigurasi publikasi dari repositori lokal ke halaman pengujian, dan tidak segera "mendorong"? Faktanya adalah bahwa ketika Anda mempublikasikan semua halaman diterbitkan kembali setiap kali dan menggiling perubahan yang dibuat secara manual atau komentar di baris (inline). Oleh karena itu, ketika dokumen sedang dalam proses, kami memutuskan untuk menerbitkannya di halaman terpisah, seperti mode dev, untuk menambahkan versi yang telah diterbitkan ke dalam ulasan dan mengumpulkan komentar.
Dalam CI, publikasi diimplementasikan sebagai tahap terpisah dalam pipa Jenkins, di dalam tahap ini gambar buruh pelabuhan diluncurkan pada registri jarak jauh, yang mengimplementasikan sphinx-build dengan konfigurasi yang diinginkan. Lebih baik segera lewati langkah ini.
pipeline { agent { label "${AGENT_LABEL}" } stage("Documentation") { steps { ansiColor('xterm') { withCredentials([usernamePassword( credentialsId: "${DOCUMENTATION_BOT}", usernameVariable: 'CONFLUENCE_USERNAME', passwordVariable: 'CONFLUENCE_PASSWORD' )]) { sh "docker-compose -p $COMPOSE_ID run sphinx-doc confluence" } }} }
Di dalam panggung,
docker-compose -p release-name-run run sphinx-doc sebenarnya diluncurkan. Jenkinsfile, pada gilirannya, menggambarkan ketergantungan dan lingkungan di mana langkah akan dilakukan, proses mengumpulkan dan memperbarui informasi di target. Dari tes sejauh ini hanya ada pemeriksaan sintaks .md dan .rst dengan doc8 dan markdownlinter.
Nuansa lain: setiap kali Anda mempublikasikan subnet halaman, Sphinx memperbarui seluruh pohon, setiap halaman. Artinya, bahkan jika konten tidak berubah, perubahan dibuat, jika Anda memiliki notifikasi yang dikonfigurasi di saluran, maka itu akan menjadi tersumbat dengan banyak notifikasi.
Beberapa cara lagi
Foliant dengan Confluence sebagai Backend
Alat dokumentasi foliant dengan Mkdocs dan banyak preprosesor di bawah tenda dan backend dalam bentuk Confluence. Anda
dapat membaca lebih lanjut di sini , tetapi singkatnya, ia menggunakan pandoc untuk mengonversi md ke HTML, dan kemudian menerbitkannya di Confluence. Anda hanya perlu mengonfigurasi backend dan menginstal pandoc di lingkungan sebagai ketergantungan.
Perbedaan yang menguntungkan dari solusi pertama: dapat mengembalikan komentar sebaris di tempat yang sama dengan sebelum halaman diterbitkan, memungkinkan Anda membuat halaman dengan mengaturnya di konfigurasi, mengedit nama mereka, dan juga memasukkan konten ke halaman yang ada, untuk ini Anda perlu mengatur secara manual jangkar foliant pada halaman dalam pertemuan.
Ini hanya berfungsi dengan sumber pada penurunan harga.
Metro
Multitool yang menerbitkan beragam format sumber dalam Confluence, dari Google Documents hingga Salesforce Quip, dan juga dalam Markdown.
Untuk mempublikasikan, Anda perlu meletakkan file manifest.json di folder tempat file .md Anda berada, tentukan folder di dalamnya, file yang ingin Anda terbitkan, untuk setiap file tentukan id halaman pertemuan. Judul halaman akan menjadi judul pertama dalam file (#). Alat ini memiliki beberapa penyimpangan dengan markdown Markdown, jadi perhatikan
dermaga . Lampiran dan gambar harus diletakkan di folder yang sama, dan alat ini juga memungkinkan Anda menentukan penggunaan daftar isi secara langsung di konfigurasi.
Permata md2conf
Ruby gem
md2conf , itu mengonversi Markdown ke asli untuk Confluence XHTML. Kemudian Anda dapat menulis tugas Rake, yang pada gilirannya dapat dipanggil melalui Gitlab CI / Jenkins untuk mendorong ke master, lalu tarik API Confluence untuk menerbitkan halaman. Agar Anda tidak membawa lingkungan Ruby kepada Anda, bungkus dependensi untuk permata ini dalam sebuah wadah.
Cara mengirim permintaan ke Confluence API dijelaskan di
sini .
Ini hanya berfungsi dengan sumber pada penurunan harga.
Dari ditemukan di Github
Sebenarnya, sejumlah skrip atau cli-tools telah dilakukan di komunitas, tapi saya hanya bereksperimen dengan md2conf, semuanya dibagi menjadi dua kelompok.
Yang baru saja mengonversi format (md, asciidoc, rst -> confluence / xhtml):Yang paling bijaksana dari mereka yang saya lihat adalah yang ini (https://github.com/rogerwelin/markdown2confluence-server), penulis langsung menulis Dockerfile, yang mengangkat cli-tool sebagai server REST, maka Anda dapat mengirim paket permintaan konversi ke sana .
Dan orang-orang yang segera mengimplementasikan sendiri permintaan ke API pertemuan , Anda hanya perlu menentukan kunci API di konfigurasi:
Pilih salah satu opsi (tergantung pada bahasa markup Anda dan susun) dan kumpulkan pipeline Anda tergantung pada tugas yang Anda hadapi.
NB Jika Anda berbagi komentar yang menemukan solusi lain untuk masalah ini, saya akan sangat berterima kasih.
Dan jika Anda ingin berbicara lebih banyak tentang topik ini dengan saya, datanglah ke KnowledgeConf 2020 pada 18 Mei.