Lewati ke isi

Panduang penggunaan Mkdocs untuk dokumentasi proyek

MkDocs.org adalah aplikasi berbasis Python yang dapat digunakan untuk membuat halaman dokumentasi sederhana untuk suatu proyek. Pada tulisan ini akan dibahas 3 cara dalam menjalankan MkDocs, diantaranya:

  1. Instalasi native; dimana aplikasi MkDocs dan depedencies nya akan diinstall sesuai dengan sistem operasi yang digunakan.
  2. Docker: prebuilt image; menggunakan Docker dan prebuilt image, lalu melakukan instalasi seperti poin 1 pada sistem basis Linux; dan yang terakhir adalah.
  3. Docker: custom image; membuat Docker image khusus untuk menjalankan MkDocs, agar dapat digunakan berkelanjutan.

Lingkup utama

Pembahasan kali ini terfokus kepada poin ke-3, dimana MkDocs akan dijalankan pada Docker dengan image khusus. Alasan utamanya adalah agar dapat didistribusikan dengan mudah lintas sistem operasi. Selain alasan pembelajanan dan pembiasaan, diharapkan dapat juga menghilangkan permasalahan tidak dapat

Pesyaratan sistem

  • Docker versi terbaru
  • Git client
  • Akses terhadap repositori Biztech-Docs
  • Editor teks, untuk menuliskan dokumentasi. Disarankan menggunakan SublimeText3
  • Peramban web (Firefox, Chrome, Opera, Safari. Edge, atau lainnya) versi termutakhir.

Instalasi native

Bagian ini belum selesai didokumentasikan, silakan lihat Mkdocs - Instalation dan bantu kembangkan bagian panduan ini.

Docker: prebuilt image

Menjalankan kontainer Docker dengan basis python 3.8.1 lalu masuk ke bash

docker container run --rm -it \
    --name mkdocs \
    --hostname mkdocs \
    --publish 8000:8000 \
    --volume "$PWD":/pages \
    --workdir /pages \
    python:3.8.1-slim-buster bash

Docker akan menjalankan kontainer dan masuk ke dalam sesi bash. Setelah itu lakukan instalasi pip, mkdocs, tema mkdocs-material, dan ekstensi untuk penyorotan sintaks.

pip install --upgrade pip && \
  pip install \
    mkdocs \
    mkdocs-minify-plugin \
    Pygments \
    markdown \
    pymdown-extensions \
    mkdocs-material

Setelah seluruh proses instalasi selesai, pada terminal ketikan

mkdocs serve -v

Docker: custom image

Untuk mengunakan metode ini, terlebih dahulu kita perlu memastikan atau meyiapkan berkas Dockerfile. Dari pengaturan pada berkas tersebut dapat dibuat image baru yang sudah memuat pustaka-pustaka yang akan digunakan seperti yang terdapat pada metode Docker: prebuilt image. Mengapa medote ini yang dijadikan pilihan? Alasannya dapat dilihat diatas

# mkdocs-material:1.0.4-4.1.2
FROM python:3.8.1-slim-buster

# Jawara image Docker ini
LABEL maintainer="Adek Lanin <[email protected]>"

# Uraian singkat
LABEL description="Docker image ini mengadopsi mkdocs-1.0.4 dengan tema mkdocs-material-4.6.0 pada komputer lokal dan sudah disesuaikan dengan kebutuhan Biztech"

# Instalasi pip
RUN pip install --upgrade pip \
    && pip install \
        mkdocs>=1.0 \
        mkdocs-minify-plugin>=0.2 \
        Pygments>=2.5 \
        markdown>=3.2 \
        pymdown-extensions>=6.3 \
        mkdocs-material>=4.6 \
    && rm -rf ~/.cache/pip # Membersihkan cache hasil instalasi untuk mengurangi ukuran image

# Menentukan direktori yang akan digunakan nanti pada saat menjalankan kontainer
WORKDIR /pages

# Membuka porta bagi akses dari mesin lokal
EXPOSE 8000

Kemudian jalankan perintah build, dengan akhiran . yang merujuk kepada direktori lokasi dari berkas Dockerfile

docker image build -t mkdocs-material:1.0.4-4.6.0 .

Pastikan perintah di atas dijalanan pada direktori yang sama dengan lokasi berkas Dockerfile. Setelah proses pembuatan image khusus tersebut selesai, masih pada direktori yang saja buat kontainer Docker dengan perintah di bawah.

docker container run -it --rm \
    -p 8000:8000 \
    -v $PWD:/pages \
    mkdocs-material:1.0.4-4.6.2 \
    mkdocs serve -v

Silakan buka dan kunjungi laman localhost:8080.