DocC atau Documentation Compiler, adalah tool dari Apple yang bisa kita gunakan dalam membuat Developer Documentation untuk aplikasi, framework, dan package yang kita buat.

Jika kamu pernah membaca dokumentasi dari UIKit, Core Data, MapKit, atau bahkan Tutorial SwiftUI yang sangat interaktif, semua itu dibuat menggunakan DocC.

Diagram DocC

DocC menghasilkan dokumen dari 2 input, yang pertama adalah dari Source Code kita, kedua yaitu dari DocC Catalog (opsional), DocC Catalog adalah file dokumentasi yang kita buat secara custom, berisi kumpulan artikel, extension, serta tutorial terkait dengan framework atau package yang kita buat.

Untuk mempublikasikan dokumentasi yang telah kita buat, kita bisa mengirimkan file .doccarchive secara langsung, yang nantinya bisa dibuka melalui Xcode. Atau opsi kedua, kita bisa deploy ke web server, karena file .doccarchive berisi kumpulan file html, js, css, dll.

Isi file .doccarchive

Berikut adalah beberapa kelebihan DocC dibandingkan dengan tools lain:

1. Auto Generate dari Source Code

2. Auto Completion

3. Terintegrasi dengan Xcode

4. Interactive Tutorial

5. Official dari Apple

Pertama silakan buka salah satu project-mu, atau bisa juga menggunakan sample project yang telah saya buat untuk mendemokan tutorial ini, sebuah Swift Package untuk menghitung Body Mass Index (BMI).

Kamu bisa download di sini: https://github.com/alfinsyahruddin/bmi-calculator/tree/starter

Di project tersebut ada 2 branch, pilih yang starter.

Untuk membuat dokumentasi, ada 2 cara:

1. Pilih menu Product -> Build Documentation

2. Atau menggunakan shortcut: ctrl + shift + command + D

Documentation

Maka, dokumentasi akan terbuat secara otomatis dari source code kita! 🎉

DocC mempunyai beberapa syntax atau aturan penulisan dalam pembuatan dokumentasi, bernama "Documentation Markup"

Seperti yang telah kita ketahui, ada 2 input yang digunakan DocC untuk membuat dokumen. Yang pertama adalah dari source code kita, nah kita bisa menambahkan deskripsi dan penjelasan pada source code kita melalui Code Comments agar terdokumentasi dengan lebih baik.

Untuk menambahkan deskripsi ada 2 cara, yaitu menggunakan /// atau /** diakhiri dengan */, contohnya seperti ini:

Copy
1/// ``BmiStatus`` is an enum of Body Mass Index (BMI) statuses.
2public enum BmiStatus {
3    case underWeight
4    case normal
5    case overWeight
6    case obese
7}

Copy
1/**
2 ``BmiError`` is an enum of Body Mass Index (BMI) Errors.
3 */
4public enum BmiError: Error {
5    case invalidIndex
6}

Kita juga bisa menambahkan beberapa atribut untuk function atau method yang kita buat, seperti Parameters, Returns, dan Throws.

Copy
1/**
2This method is for calculating Body Mass Index (BMI).
3
4- Parameters:
5    - weight: The weight of body (in kilograms).
6    - height: The height of body (in meters).
7
8- Returns: The result of BMI calculation.
9
10- Throws: `BmiError.invalidIndex` if failed to get status due to invalid BMI index.
11*/
12public func calculateBmi(
13    weight: Double,
14    height: Double
15) throws -> BmiResult {
16    let index = weight / pow(height, 2)
17
18    return BmiResult(
19        index: index,
20        status: try self.getBmiStatus(index)
21    )
22}

Dan jika orang lain menekan "command + click" pada function kita, maka hasilnya akan seperti ini:

Preview

DocC Catalog adalah file dokumentasi yang kita buat secara custom, berisi kumpulan artikel, extension, serta tutorial terkait dengan framework atau package yang kita buat.

Untuk membuat DocC Catalog, caranya kita pilih menu "File -> New -> File" atau ketika kita baru pertama kali membuat project, centang opsi "Include Documentation"

Berikut adalah beberapa syntax untuk menulis dokumentasi pada DocC Catalog:

Pada dasarnya DocC menggunakan Markdown sebagai Syntax untuk penulisan dokumentasi. Kamu bisa belajar Markdown dari sini: https://www.markdownguide.org/cheat-sheet/

Untuk menambahkan gambar pada dokumentasi kita, caranya kita drag & drop file gambar kita ke dalam folder "Resources", kemudian kita tampilkan menggunakan syntax Markdown.

Copy
1![Package Icon](/assets/article-images/docc-tutorial/aWNvbg.icon)

Namun, format nama file-nya terdapat sedikit perbedaan dengan Markdown biasa:

Jika kita ingin membuat link referensi ke artikel yang kita buat, caranya seperti ini:

Copy
1<doc:Installation>

Jika kita ingin membuat link referensi ke Symbol seperti Class, Method, Enum, dll. Caranya seperti ini:

Copy
1``BmiCalculator``
2
3``BmiCalculator/BmiStatus``
4
5``BmiCalculator/BmiCalculator/calculateBmi(weight:height:)``

Landing Page adalah halaman awal dari dokumentasi kita, nah DocC memungkinkan kita untuk mengkustomisasi Landing Page tersebut, seperti menambahkan gambar, overview, topics, dll.

Landing Page

Untuk membuat custom Landing Page, caranya seperti ini:

1. Klik "Documentation.docc" pada Project Navigator.

2. Pilih File -> New -> File

3. Pilih "Empty"

4. Pastikan nama file-nya sama dengan nama Target dari Product Module, misalnya nama targetnya adalah "BmiCalculator" maka berilah nama "BmiCalculator.md"

5. Terakhir, di file "BmiCalculator.md" bagian paling atas, tambahkan header yang berisi nama target dengan diapit 2 backslash seperti ini:

BmiCalculator.md
Copy
1# ``BmiCalculator``
2
3BmiCalculator is a Swift package for calculate Body Mass Index (BMI).
4
5...

Setelah itu kamu bisa mengedit file Landing Page tersebut sesuai dengan kebutuhan.

Untuk membuat artikel, caranya kita pilih "File -> New -> File" kemudian pilih "Article File"

Artikel

Kita juga bisa mengelompokkan artikel-artikel yang telah kita buat, silakan buka file Landing Page yang telah kamu buat, dan tambahkan teks berikut:

BmiCalculator.md
Copy
1...
2
3## Topics
4
5### Getting Started
6
7- <doc:Installation>
8
9### Tutorials
10
11- <doc:CalculateBmi>
12- <doc:GetBmiStatus>

Grouping Artikel

Jika kita ingin menambahkan penjelasan, gambar, dll pada Symbol (class, struct, enum, dll) caranya seperti ini:

1. Klik "Documentation.docc" pada Project Navigator.

2. Pilih File -> New -> File

3. Pilih "Extension File"

4. Pastikan nama file-nya sama dengan nama Symbol yang ingin kita buat extension-nya

Setelah itu sesuaikan judul dengan ref symbol nya, dan tambahkan code berikut:

Copy
1@Metadata {
2    @DocumentationExtension(mergeBehavior: append)
3}

Selain append, ada juga opsi override jika kita ingin meng-override Code Comment yang sudah ada pada source code tersebut.

Berikut adalah contoh jika kita ingin membuat Extension untuk enum BmiStatus :

BmiStatus.md
Copy
1# `BmiCalculator/BmiStatus`
2
3@Metadata {
4    @DocumentationExtension(mergeBehavior: append)
5}
6
7## Formula
8
9- underWeight: < 18.5
10- normal: 18.5 <= 25
11- overWeight: 25 <= 30
12- obese: > 30

Extension

Untuk melihat versi web dari dokumentasi yang telah kita buat, silakan buka terminal dan ikuti langkah berikut:

1. Jalankan command berikut untuk generate file ".doccarchive" di dalam folder "docc":

Copy
1xcodebuild docbuild -scheme BmiCalculator -derivedDataPath docc -destination 'generic/platform=iOS';

2. Jalankan command berikut untuk mengubah file ".doccarchive" menjadi file web yang diakses, ke dalam folder "docs":

Copy
1$(xcrun --find docc) process-archive transform-for-static-hosting docc/Build/Products/Debug-iphoneos/BmiCalculator.doccarchive --output-path docs;

3. Serve file web dari folder "docs" agar bisa diakses:

Copy
1python3 -m http.server --dir=docs

Kemudian buka http://localhost:8000/documentation/bmicalculator/

http://localhost:8000/documentation/bmicalculator/

Sekarang, kita akan mencoba untuk melakukan deployment ke Github Pages menggunakan CI/CD. Agar tiap kali kita push ke github, dokumentasi kita juga akan terdeploy secara otomatis!

1. Pertama, buka repository Github-mu, kemudian klik "Settings"

2. Pilih menu "Pages"

3. Di bagian Build and deployment -> Source pilih "Github Actions"

Github Actions

4. Buat file baru bernama "publish-pages.yml" di dalam folder ".github/workflows/" yang berisi code berikut:

publish-pages.yml
Copy
1# Name your workflow.
2name: Deploy DocC
3on:
4  # Runs on pushes targeting the default branch
5  push:
6    branches: ["main"]
7# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
8permissions:
9  contents: read
10  pages: write
11  id-token: write
12# Allow one concurrent deployment
13concurrency:
14  group: "pages"
15  cancel-in-progress: true
16jobs:
17  # Single deploy job since we're just deploying
18  deploy:
19    environment:
20      # Must be set to this for deploying to GitHub Pages
21      name: github-pages
22      url: ${{ steps.deployment.outputs.page_url }}
23    runs-on: macos-12
24    steps:
25      - name: Checkout 🛎️
26        uses: actions/checkout@v3
27      - name: Build DocC
28        run: |
29          xcodebuild docbuild -scheme BmiCalculator \
30            -derivedDataPath /tmp/docbuild \
31            -destination 'generic/platform=iOS';
32          $(xcrun --find docc) process-archive \
33            transform-for-static-hosting /tmp/docbuild/Build/Products/Debug-iphoneos/BmiCalculator.doccarchive \
34            --hosting-base-path bmi-calculator \
35            --output-path docs;
36          echo "<script>window.location.href += \"/documentation/bmicalculator\"</script>" > docs/index.html;
37      - name: Upload artifact
38        uses: actions/upload-pages-artifact@v1
39        with:
40          # Upload only docs directory
41          path: "docs"
42      - name: Deploy to GitHub Pages
43        id: deployment
44        uses: actions/deploy-pages@v1

5. Kemudian lakukan commit & push ke Github!

6. Maka proses deployment akan berjalan dan tunggu prosesnya sampai selesai.

Actions

Sekarang, website dokumentasi kita telah bisa diakses oleh publik di: https://[USERNAME_GITHUB].github.io/bmi-calculator 🎉

https://alfinsyahruddin.github.io/bmi-calculator

Jika kamu tertarik dan ingin mempelajari lebih dalam mengenai DocC, seperti cara Localization, membuat Interactive Tutorial, deploy ke Apache Web Server, dll. Kamu bisa membaca dokumentasinya di sini: https://developer.apple.com/documentation/docc

Oke mungkin itu saja yang bisa saya bagikan kali ini, kalau kamu merasa artikel ini bermanfaat silakan Like & Share artikel ini ke teman-teman kamu atau jika kamu punya pertanyaan, tulis aja di kolom komentar, Thank you! 😁 🙏