Một vài tuần trước, tôi đã giới thiệu SassDoc tại SitePoint trong khi nó vẫn còn trong giai đoạn phát triển ban đầu. Kể từ đó, chúng tôi đã phát hành không ít hơn một lớn và hai phiên bản nhỏ, lần lượt là: 1.0.0, 1.1.0 và 1.2.0. Chúng tôi đã vận chuyển khá nhiều tính năng trong khi làm điều đó, vì vậy tôi nghĩ rằng nó sẽ là một ý tưởng tốt để giới thiệu cho họ.
Nếu bạn chưa quen thuộc với SassDoc, cho phép tôi giới thiệu nó.
SassDoc là gì?
SassDoc là Sass gì JSDoc là JavaScript: một công cụ tài liệu dựa trên ý kiến trong các tập tin công việc của bạn. Kịch bản thông thường là để bình luận cho các chức năng của bạn, mixins và các biến sau khi tài liệu hướng dẫn, chạy SassDoc từ dòng lệnh và bùng nổ. Bạn phải tự mình tạo ra tài liệu.
A View tốt hơn
Khi tôi lần đầu tiên giới thiệu SassDoc, các tài liệu được tạo ra là không sao, tôi đoán. Trong khi đó, tôi thực sự muốn cải thiện thiết kế bởi vì, khi tất cả nói và làm, nếu bạn nói với ai đó bạn sẽ tạo ra tài liệu đẹp cho họ, bạn sẽ nhận được những điều tốt hơn quyền và cho họ một cái gì đó tuyệt vời!
Điều này nêu ra những ý kiến khá giảm nhẹ phải trung thực (thậm chí tôi có đặt phòng của tôi). Điều đó đang được nói, vẻ đẹp là trong mắt của khán giả, vì vậy tôi giữ này dưới chiếc mũ của tôi và đến với một thiết kế lấy cảm hứng từ thiết kế mới của Google.
Thiết kế web ở Đà Nẵng hy vọng bạn thích nó!
Cùng với các thương hiệu xem bóng mới này, chúng tôi đã thêm một công cụ tìm kiếm mờ nhẹ dựa trên chì. Điều này sẽ làm cho nó dễ dàng hơn cho những người có một số lượng lớn các mặt hàng tài liệu để nhanh chóng đạt được điều mà họ đang tìm kiếm mà không cần phải di chuyển mãi mãi. Dọc theo đường cùng, chúng tôi đã thanh bên cố định trong chủ đề mặc định để bạn có thể giữ một mắt trên cấu trúc dữ liệu ở tất cả các thời gian.
Chủ đề và tùy chỉnh Templates
Trong phiên bản 1.0.0, chúng tôi đã làm cho nó có thể cho bạn để thương hiệu xem bằng cách cung cấp một đường dẫn đến một tập tin cấu hình có chứa một số thông tin về dự án của bạn, giống như tên, phiên bản, mô tả, giấy phép và như vậy. Điều thú vị là, nếu bạn xảy ra để có một tập tin package.json (dự án npm) ở cấp cơ, chúng ta sử dụng nó, do đó bạn không cần phải sao chép thông tin của dự án của bạn cho SassDoc. Vì vậy, đó là khá tốt đẹp.
Trong 1.2 chúng tôi muốn đẩy mọi thứ hơn nữa. Giống như waaay thêm. Mục tiêu của chúng tôi là cung cấp cho bạn khả năng sử dụng các chủ đề tùy chỉnh của bạn và các mẫu tùy chỉnh của bạn (với mẫu động cơ yêu thích của bạn). Về cơ bản, chúng tôi muốn trao dữ liệu cho bạn để bạn có thể làm bất cứ điều gì bạn muốn với nó. Như vậy:
1
sassdoc src / thư mục đích / thư mục --theme của tôi-tuyệt vời-chủ đề
Lưu ý: Khi bạn thiết lập các tùy chọn --theme của giao diện cli, SassDoc sẽ tìm kiếm một gói sassdoc-theme-foo, sau đó ./foo, và cuối cùng foo.
Trong khi đó, chúng tôi không muốn làm những điều quá khó khăn về phía bạn vì vậy chúng tôi đã có thiên tài JavaScript của chúng tôi Valerian Galliat xây dựng một công cụ theming: Themeleon. Đây là một dự án độc lập được xây dựng cho SassDoc nhưng hoàn toàn độc lập với nó. Đó là một chủ đề nhỏ Node động cơ chạy nhỏ với khoảng 100 dòng mã JavaScript.
Bạn không bắt buộc phải sử dụng Themeleon cắm chủ đề của bạn vào SassDoc, mặc dù nó làm cho con đường công việc dễ dàng hơn bởi vì nó giữ tất cả các bụi bẩn kỹ thuật dưới mui xe. Ngoài ra, nó đi kèm với một mixin (loại một plugin) cho cả hai mẫu động cơ Uống một lân (themeleon-uống một lân) và Jade (themeleon-ngọc bích), để ngăn cản bạn thậm chí còn phải làm những gì xảy ra tiếp theo.
Valerian đã viết một giới thiệu chuyên sâu để xây dựng và sử dụng các chủ đề riêng của bạn, vì vậy tôi sẽ chỉ bao gồm các vấn đề cơ bản ở đây.
Tất cả các chủ đề đã làm là phơi bày một chức năng triển khai thực hiện giao diện sau đây:
/ **
* @ Param string} {đích Directory để làm chủ đề trong.
* @ Param {đối tượng} Biến ctx để vượt qua các chủ đề.
* @ Trả lời hứa {} Promises A / A + thực hiện.
* /
module.exports = function (đích, CTX) {
...
};
Từ đó Themeleon có chịu trách nhiệm về tất cả mọi thứ và cho phép bạn viết chủ đề của bạn mà không làm phiền với "cấp thấp" xem xét, xử lý như hứa hẹn, gọi điện fs liệu, đảm bảo các thư mục đích tồn tại, và như vậy.
Sau đó, nó là tất cả về việc tạo ra một tập tin package.json đòi hỏi một số phụ thuộc (bao gồm cả themeleon và mẫu động cơ của bạn, ví dụ themeleon-ngụm, themeleon-ngọc hoặc bất kỳ). Cũng như một thư mục chứa tập tin index.js như được giải thích trong tài liệu. Sau đó, tập tin JavaScript này sẽ mô tả các quá trình để tạo ra sản lượng.
Trong chủ đề mặc định của chúng tôi sử dụng themeleon-ngụm, nó cũng đơn giản như:
var themeleon = yêu cầu ('themeleon') () sử dụng ('ngụm').
module.exports = themeleon (__ dirname, chức năng (t) {
t.copy ('tài sản');
t.swig ('views / tài liệu / index.html.swig', 'index.html');
});
Vậy đó! Nếu bạn có kế hoạch xây dựng chủ đề của riêng bạn, bạn sẽ hài lòng khi biết rằng chúng tôi đã thực hiện một soạn để giúp bạn bắt đầu. Đi trước và đọc các tài liệu, viết vài dòng và bạn sẽ được tốt để đi. Ngoài ra, cảm thấy tự do để yêu cầu giúp đỡ nào!
Tập hợp các mục của bạn vào Nhóm
Một tính năng mà chúng tôi đã thực sự được mong muốn trong một thời gian bây giờ là khả năng để bạn có thể thu thập các mục của bạn thành các nhóm. Lúc đầu, chúng tôi nhóm các mặt hàng theo kiểu của họ: chức năng, mixin và biến. Khi ghi một API duy nhất, đó là tốt nhưng khi chạy SassDoc vào các dự án lớn hơn nó cảm thấy một chút đi.
Vì vậy, bây giờ bạn có thể sử dụng chú thíchgroup theo sau là một chuỗi để xác định một nhóm cho một mục nhờ công việc tuyệt vời của Fabrice Weinberg. Tất cả các mục chia sẻ cùng một nhóm sẽ được hiển thị trong phần tương tự. Chúng tôi tiếp tục loại nhóm, do đó vào cuối ngày, nó hoạt động như thế này: nhóm> type> mục. Trong khi đó tất cả các mục mà không có chú thíchgroup sẽ được thu thập trong một nhóm không xác định.
Để cho phép bạn đặt tên cho nhóm của bạn theo cách bạn muốn, chúng tôi đã thêm một hệ thống răng cưa. Ví dụ, nếu bạn khai báo một nhóm với những người giúp đỡgroup, bạn có thể thêm một bí danh của nó trong cấu hình để nó được hiển thị như "Helpers và Công cụ" ví dụ. Điều này đặc biệt hữu ích khi bạn muốn đổi tên nhóm mặc định không xác định vào một cái gì đó thân thiện hơn như "chung" hay bất cứ điều gì.
Grunt, Gulp và Bông cải xanh Plugins
Nếu bạn sẵn sàng để kết hợp SassDoc như một phần của quá trình triển khai, bạn sẽ hài lòng khi biết chúng tôi đã có một plugin Grunt, một plugin Gulp và một plugin Bông cải xanh, tất cả được thực hiện bởi Pascal Duez. Sử dụng chúng rất đơn giản nếu bạn đã quen thuộc với cách mỗi Á hậu nhiệm vụ hoạt động:
/ * Gulp * /
gulp.task ('sassdoc', function () {
trở lại ngụm
.src ('path / to / source')
.pipe (sassdoc ({
ĐÍCH: 'path / to / tài liệu'
}));
});
/ * Grunt * /
grunt.initConfig ({
sassdoc: {
mặc định: {
src: 'path / to / nguồn',
ĐÍCH: 'path / to / tài liệu'
}
},
});
/ * Bông cải xanh * /
var sassdoc = yêu cầu ('bông cải xanh-sassdoc');
var = sassdoc tài liệu (cây, tùy chọn);
Bạn cũng có thể thêm các tùy chọn tương tự như SassDoc thường xuyên CLI API, vì vậy hãy đọc README từ các kho lưu trữ để tìm hiểu thêm về cách làm như vậy!
Liên kết Nguồn
Nếu có một điều tôi thực sự thích trong tài liệu của bất cứ loại nào đó là khả năng đi thẳng vào mã nguồn. Do đó nó không có bất ngờ chúng tôi đã thêm một tính năng xem mã nguồn để SassDoc.
Bởi vì điều này liên quan chặt chẽ đến xem, nó giống như một tính năng chủ đề hơn so với một cái gì đó từ SassDoc chính nó. Để đơn giản, nó cần một con đường cơ bản từ các tập tin cấu hình, sau đó liên kết với mã nguồn được tạo ra sử dụng basePath + item.file.path, các con sau này tính bằng SassDoc. Vì lý do đó, chúng tôi khuyên bạn luôn luôn chạy SassDoc từ thư mục gốc của dự án của bạn (nó giúp trong nhiều trường hợp).
Tiếp theo là gì?
Vui mừng bạn hỏi! Chúng tôi có vẫn pleeeenty ý tưởng cho tương lai của SassDoc, và chúng tôi chắc chắn rằng bạn có một số ý kiến thú vị cho mình. Đừng giữ chúng cho chính mình; chia sẻ chúng trên kho!
Trong khi đó, thiet ke web o da nang đang làm việc trên:
một chú thíchoutput, tương tự như @ trả lại nhưng đối với mixins (# 133)
làm cho nó có thể để tài liệu bản đồ Sass một cách tốt hơn (# 25)
cho khả năng xem trước toàn bộ chức năng / mixin trực tiếp từ tài liệu (# 124)
Đăng nhận xét