简介
在前端开发中，我们不仅需要良好的代码编写，也需要合适的文档来解释我们的工作。在这方面，@angularclass/dope-docs 是一个值得使用的npm包，可以帮助我们简单地创建优秀的文档。
@angularclass/dope-docs是一个基于Angular2的模块，用于创建反应式文档，其通过支持Markdown和HTML标记以及代码演示和截图等功能对文档进行了优化和升级。
在本篇文章中，我们将介绍如何使用它来快速创建文档以及如何进行一些自定义设置。
安装
在使用dope-docs之前，请先确保您已经安装了最新版本的Node.js和Angular/cli。
我们可以通过以下命令来安装@dope-docs：
npm install @angularclass/dope-docs
步骤
新建文档项目
- 运行以下命令来创建一个文档项目：
ng new dope-docs-demo
- 进入新项目的根目录，并使用以下命令来安装@dope-docs：
npm install @angularclass/dope-docs --save-dev
- 创建一个文档布局，并在 app.module.ts 文件中引入并设置 @dope-docs 编译器：
-- -------------------- ---- -------
------ - -------- - ---- ----------------
------ - --------------- ---------------- - ---- --------------------------
------ - ------------ - ---- ------------------
-----------
------------- -
------------
--
-------- -
--------------
--
---------- -
-
-------- -----------------
--------- ----------------
-
--
---------- --------------
--
------ ----- --------- - -创建文档示例
在项目根目录创建一个 markdown 文件：
src/docs/docs.md
在 docs.md 中编写以下内容：
-- -------------------- ---- ------- - ------- - ------- -- - -------- --- -------- ------ --- ------- --- ------------- -- ---- -- ------- - ------- -- - ----------- -------- --- -------- ------ --- ------- --- ------------- - -- -- ------- -- ---------- --- -- ----- -- --- ------ --- ---------- - ------- -- ------ -- ------ --- -- ---- -- ---- --------- ------ --- ------ -- ---------- -- ------- - ---- -- --- ---------- -- ----- ------- ---- - ------ ----------- --- -- --- --- -- --------------- ------------- - ----------- -- ----------- -----
这段代码描述了Angular框架的一些基本信息。
接下来，我们将在组件中通过MarkdownReceiver指令读取和显示此markdown内容：
<dope-docs [document]="'./docs.md'">
<markdown-receiver></markdown-receiver>
</dope-docs>在我们的组件中，我们可以通过HttpClient从markdown文件中读取文档内容，并将其传递给MarkdownReceiver组件。
-- -------------------- ---- -------
------ - ---------- ------ - ---- ----------------
------ - ---------- - ---- -----------------------
------ - ---------------- - ---- --------------------------
------------
--------- -----------
--------- -
---------- -------------------------
---------------------------------------
------------
-
--
------ ----- ------------ ---------- ------ -
----------- - -------------------
------------------- ----- -----------
------- ----------------- ----------------- -
-
---------- -
------------------------------- -------------- ----------------------------- -- -
----------------------------------------
---
-
-现在，您可以运行项目并在浏览器中查看文档内容。
在文档中添加示例代码
@dope-docs 还支持在 Markdown 中嵌入示例代码。下面是一个示例代码：
-- -------------------- ---- ------- - -------- ---- ------ ------------ - ---- ---- ----------- -- ---- ------ ------------- ------ ----------- ---- ---------------- ------------ --------- --------- --------- ------------- ------------------------- -- ------ ----- ------------ - -
以上代码将在文档中呈现一个 Angular 组件，该组件渲染一个 h1 标题。
为了支持此功能，需要添加一个额外的参数skipAssets=true至DopeDocsCompiler构造函数。下面是 Angular 组件代码：
-- -------------------- ---- -------
------ - ---------- ------ - ---- ----------------
------ - ---------- - ---- -----------------------
------ - ---------------- - ---- --------------------------
------ - ---------------- - ---- --------------------------
------------
--------- -----------
--------- -
-------------- ----------------------------
----------------------------------------------
-------------------
---- ------------------
---- -----------------
---- --------- ----------------------
---- ------------------- ---------------
---- -----------
----- ----------------------------
------ ----------- ---- ----------------
------------
--------- ---------
--------- ------------- -------------------------
--
------ ----- ------------ -
-
-------
------
------
------
------
-
--
------ ----- ------------ ---------- ------ -
----------- - -------------------
------------------- ----- -----------
------- ----------------- ----------------- -
-
---------- -
-- ------------------------------- -------------- ----------------------------- -- -
-- ----------------------------------------
-- ---
-
-现在，启动应用程序并查看文档中的示例代码。
结论
@dope-docs npm包为我们提供了一种快速创建文档和添加示例代码的方法。希望这篇文章能够帮助您开始使用它，并且从中得到收获。如果您对代码有任何疑问或建议，欢迎在下面发表评论或提出问题。
祝您好运！
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/112265