Hướng dẫn viết tài liệu trên local¶

1. Requirements¶

Eclipse + Pydev

Python 3.8 venv

Git

Có SSH key cho tài khoản github

2. Lấy mã nguồn về local¶

Truy cập vào đường dẫn https://github.com/Viindoo/documentation. Nếu KHÔNG truy cập được thì thực hiện các bước sau:

Tạo tài khoản github, một tài khoản github phải có đầy đủ 2 thông tin sau để dễ dàng nhận diện:

Name = Tên trên hồ sơ nhân viên

Avatar

Mở Eclipse

Truy cập vào menu File > Import

Chọn Project from Git

Next và paste đường dẫn git@github.com:Viindoo/documentation.git vào ô URI

Next

Next và điền thông tin:

Directory: /home/leotran/git/documentation/documentation14 vào ô Directory. Lưu ý: thay leotran = tên đăng nhập trên máy

Initial branch: 14.0. Có thể thay bằng 15.0, 16.0,... nếu muốn

Next và chọn Import using the New Project wizard

Finish và chọn Pydev Project

Next

Bỏ tích Use default và click vào nút Browse

Chọn đến đường dẫn đã khai báo ở bước 7 (xem ảnh bên dưới): /home/leotran/git/documentation/documentation14 và hoàn thành các thông tin sau

Viết tài liệu

Interpreter: python3.8-venv-odoo14

Next và Finish

LƯU Ý: phần này chỉ thực hiện 1 lần đầu tiên

3. Cài đặt requirements¶

Mở màn hình Terminal hoặc nhấn tổ hợp bàn phím Ctrl + alt + T

Gõ lệnh: cd /home/leotran/git/documentation/documentation14 lưu ý đây là đường dẫn lưu mã nguồn đã khai báo ở bước 7 hoặc bước 12 ở trên

Gõ lệnh: source /home/leotran/python3.8-venv/odoo14/bin/activate Trong đó /home/leotran/python3.8-venv/odoo14 là đường dẫn python venv cho Odoo 14 đã được đào tạo trước đó

Gõ lệnh: pip install -r requirements.txt

Sau khi cài đặt xong thì chạy lại lệnh trên để kiểm tra lại. Nếu kết quả như hình dưới đây thì việc cài đặt đã thành công

LƯU Ý: phần này chỉ thực hiện 1 lần đầu tiên

4. Preview tài liệu dưới local¶

Gõ lệnh: cd /home/leotran/git/documentation/documentation14 lưu ý đây là đường dẫn lưu mã nguồn đã khai báo ở bước 7 hoặc bước 12 ở trên. Lưu ý: nếu trên màn hình Terminal đang đứng ở đây rồi thì không cần thực hiện bước này nữa

Gõ lệnh: source /home/leotran/python3.8-venv/odoo14/bin/activate

Gõ lệnh: make clean

Gõ lệnh: make đây là câu lệnh để tạo ra trang với 1 ngôn ngữ (không có đa ngôn ngữ)

Gõ lệnh: make LANGUAGES=en,vi CURRENT_LANG=en Đây là câu lệnh để tạo ra trang tài liệu tiếng Anh (html)

Gõ lệnh: make LANGUAGES=en,vi CURRENT_LANG=vi Đây là câu lệnh để tạo ra trang tài liệu tiếng Việt (html)

Sau 2 câu lệnh trên, một file index.html sẽ được tạo ra trong thư mục /home/leotran/git/documentation/documentation14/_build/html/en,vi trong đó /home/leotran/git/documentation/documentation14 là thư mục lưu trữ mã nguồn

Truy cập vào thư mục trên và mở file index.html

LƯU Ý:

Nếu bạn không quan tâm tới đa ngôn ngữ thì có thể bỏ qua bước 5 và 6.
Việc này có thể thực hiện lặp đi lặp lại bất cứ khi nào muốn xem trước hệ thống website tài liệu dưới local. Đặc biệt khi có nội dung mới, sử dụng phần này để preview nội dung dưới local trước khi đẩy lên server

5. Tạo bản Fork:¶

Truy cập vào đường link https://github.com/Viindoo/documentation

Click vào nút Fork như hình vẽ dưới đây

Chọn tài khoản của bạn để Fork

LƯU Ý: phần này chỉ thực hiện lần đầu tiên

6. Add remote dưới Local:¶

Truy cập và đăng nhập vào https://github.com/

Click vào avatar và chọn Your Repository

Tìm và truy cập vào repository có tên documentation. Đây là bản đã được Fork ở trên

Click vào nút Code và copy đường dẫn SSH

Mở Eclipse

Chuyển sang Perspective là Git như hình vẽ dưới đây

Tìm đến project Documentation14 ở bên trái và click phải chuột vào Remotes đồng thời chọn Create Remote

Nhập Remote name (tên của bạn, viết thường, không cách trống) và tích chọn Configure fetch

Click vào nút Create

Click vào nút Change và paste đường dẫn đã copy ở bước 4 vào ô URI

Các thông tin khác giữ nguyên và click vào nút Finish

Click vào nút Save and Fetch

Chuyển lại Respective là Pydev bằng cách click vào biểu tượng cạnh bên trái của Git (xem hình vẽ tại bước số 6) để kết thúc phần này
base_url = self.env['ir.config_parameter'].sudo().get_param('web.base.url')

LƯU Ý: phần này chỉ thực hiện 1 lần đầu tiên

7. Tạo nhánh (branch) dưới Local:¶

Mở Eclipse

Viết tài liệu

Đảm bảo đang ở nhánh 14.0, nếu chưa thì cần phải Switch sang nhánh 14.0 bằng cách click phải chuột vào project documentation14 và chọn Team -> Switch To -> 14.0

Trước khi tạo nhánh mới cần lấy code mới nhất của 14.0 về

Click phải chuột vào project documentation14 và chọn Team -> Switch To -> New Branch

Nhập tên nhánh vào ô Branch name. Tên nhánh phải viết thường, ngăn cách bởi _, không có ký tự đặc biệt và phải đảm bảo format v<odoo_version>_<tinh_nang>. Ví dụ: v14_accounting_expense, v14_point_of_sale_overview, v14_add_approve_category,...

Click vào nút Finish

Tên nhánh sẽ được thể hiện ở ngay tên của project

LƯU Ý: phần này sẽ được thực hiện mỗi khi bạn định tạo **PR (để đưa code lên) trên github**

8. Quản lý Category:¶

Hệ thống tài liệu gồm 3 phần chính. 3 phần này nếu muốn thêm, sửa, xóa thì cần liên lạc với bộ phận kỹ thuật để can thiệp kỹ thuật

User Documentation: Tài liệu người dùng
Technical Documentation: Tài liệu kỹ thuật
Đóng góp

Bài tập 1: trong phần User Documentation, thêm category Approval ngang cấp với Finance

Mở Eclipse
Tạo nhánh (branch) có tên v14_add_approval_category
Mở thư mục content
Mở file applications.rst
Thêm một dòng applications/approval vào dưới dùng applications/productivity và lưu lại
Mở thư mục content > applications
Click phải chuột vào thư mục applications và chọn New -> File
Nhập tên file là approval.rst Lưu ý tên file (không tính phần đuôi .rst) phải giống hệt approval đã thêm ở bước 5
Gõ đoạn code sau vào file approval.rst

:hide-local-toc:
:display-toc:

     ========
     Approval
     ========

Save file (Ctrl + S)
Thực hiện mục số 4. Preview tài liệu để xem kết quả

Bài tập 2: Thêm 2 categories là Timesheet Approval và Overtime Approval nằm trong category Approval

Update file approval.rst thành

:hide-local-toc:
:display-toc:

     ========
     Approval
     ========

.. toctree::

 approval/timesheet
 approval/overtime

Click phải chuột vào thư mục applications (nằm trong thư mục content) và chọn New -> Folder. Nhập tên Folder name là approval (lưu ý không vết hoa)
Click phải chuột vào thư mục approval mới tạo ở trên và chọn New -> File. Nhập File name là timesheet.rst
Làm tương tự để tạo ra file overtime.rst
File timesheet.rst có nội dung như sau:

==================
Timesheet Approval
==================

File overtime.rst có nội dung như sau .. code-block:

=================
Overtime Approval
=================

Thực hiện mục số 4. Preview tài liệu để xem kết quả. Lưu ý nếu chưa nhận nội dung mới thêm vào thì có thể tắt trình duyệt đi mở lại file index.html

9. Quản lý bài viết¶

Việc tạo ra 2 file timesheet.rst và overtime.rst ở trên chính là việc thêm 2 bài viết mới cho category Approval. Nội dung trong 2 file này chính là nội dung bài viết.

Bây giờ bạn có thể viết nội dung bất kỳ vào 2 file này hoặc 1 file khác nếu bạn muốn, ví dụ file expense.rst nằm trong thư mục content > application > finance.

Nội dung bài viết được viết theo cú pháp reStructuredText

Các bài viết thuộc phần User Documentation sẽ được lưu trữ và phân cấp trong thư mục applications. Bạn có thể dựa theo category được phân cấp ở bên tay trái của file index.html để tìm ra bài viết tương ứng trong thư mục applications này

Như hình ví dụ trên, nếu bạn muốn viết bài CRM thuộc category Sales, bạn tìm đến file crm.rst trong thư mục content > applications > sales.

Như hình ví dụ trên, nếu bạn muốn viết bài CRM thuộc category Sales, bạn tìm đến file crm.rst trong thư mục content > applications > sales.

10. Tạo hoặc Update file dịch¶

Gõ lệnh: cd /home/leotran/git/documentation/documentation14. Lưu ý đây là đường dẫn lưu mã nguồn đã khai báo ở bước 7 hoặc bước 12 ở trên. Nếu trên màn hình Terminal đang đứng ở đây rồi thì không cần thực hiện bước này nữa.

Gõ lệnh: make translate.

Sau câu lệnh trên, các file ngôn ngữ tiếng Việt sẽ được tạo mới hoặc update trong thư mục locale > vi > LC_MESSAGES.

Mở file .po muốn dịch để thực hiện dịch, trong trường hợp này sẽ là file applications.po.

11. Commit và Push¶

Mở Eclipse

Đảm bảo project documentation14 đang ở nhánh mong muốn, trong trường hợp này là nhánh v14_add_approval_category

Click phải chuột vào project này

Chọn Team -> Commit

Tại màn hình commit, click vào dấu cộng như hình dưới đây để đảm bảo đã add toàn bộ những thay đổi trước khi commit

Nhập Commit Message và nhấn nút Commit and Push…

Tại màn hình Push, phần thông tin Remote chọn remote mà được add ở mục số 6.

Click vào nút Preview

Click vào nút Push

Nhấn nút Close để hoàn tất

LƯU Ý: tại bước 7 nếu chọn sai remote có thể bạn sẽ không có quyền push, vì thông thường bạn chỉ có quyền push lên bản Fork của mình

12. Tạo PR trên Github¶

Truy cập vào đường link https://github.com/Viindoo/documentation/pulls

Bạn sẽ thấy thông tin warning (nền màu vàng) như hình dưới đây

Nếu đấy đúng là nhánh mà bạn vừa push, trong trường hợp này là v14_add_approval_category thì bạn click vào nút Compare & pull request

Chỉnh sửa tiêu đề nếu cần

Nhập nội dung miêu tả của Pull Request

Request Reviewers ở bên tay phải nếu cần

Kéo chuột xuống bên dưới để review lại nội dung thay đổi trước khi tạo Pull Request

Click vào nút Create pull request

13. Review và Merge¶

Cài extension Better Pull Request for GitHub trên google chrome

F5 trình duyệt google chrome để cập nhật extension

Truy cập vào Pull Request bất kỳ trong danh sách https://github.com/Viindoo/documentation/pulls

Click vào tab Files Changed để thực hiện review

Bên tay trái là danh sách các files có sự thay đổi

Bên tay phải là nội dung thay đổi tương ứng với từng file

14. Rebase¶

15. Reset¶

16. Cách viết reStructuredText¶

Tham khảo tài liệu hướng dẫn viết reStructuredText tại https://viindoo.com/documentation/14.0/contributing/documentation/rst_cheat_sheet.html