文档模块

什么是文档模块?

文档模块是ABP框架的一个应用程序模块. 它简化了软件文档的制作. 这个模块是开源免费的.

集成

目前文档模块提供提供了两种支持的存储,Github与文件系统.

托管

文档模块是一个应用程序模块,不提供任何托管的解决方案,你可以在本地或云上托管文档.

版本

当你使用GitHub存储文档时,文档模块支持多版本. 如果你的文档具有多个版本, UI上有一个组合框,用于切换版本. 如果你选择使用文件系统存储文档, 那么它不支持多版本.

ABP框架的文档也是使用的此模块.

文档模块遵循 模块化架构最佳实践 指南.

安装

1- 下载

如果你没有现有的ABP项目, 这个步骤向你展示如何在abp.io创建一个新项目并添加文档模块. 如果你本地已经有了一个ABP项目, 那么你可以跳过这一步.

推荐使用ABP CLI创建新项目,使用以下命令行:

abp new Acme.MyProject

你也可以在浏览器中导航到 https://abp.io/get-started. 输入项目名称为 Acme.MyProject, 其它保持默认选项.

请注意,本文档包含了 Entity Framework Core 提供者 不过你也可以选择 MongoDB 做为数据库提供者.

创建新项目

2- 运行这个空项目

下载项目后, 解压压缩文档并且打开 Acme.MyProject.sln. 你可以看到这个解决方案包含了 Application, Application.Contrawcts, DbMigrator, Domain, Domain.Shared, EntityFrameworkCore, EntityFrameworkCore.DbMigations, HttpApi, HttpApi.ClientWeb 项目. 右键选择 Acme.MyProject.Web 项目设置为启动项目.

创建新项目

数据库连接字符串位于Acme.MyProject.Web项目的appsettings.json中. 如果你有不同的数据库配置, 可以修改这个连接字符串.

  1. {
  2. "ConnectionStrings": {
  3. "Default": "Server=(LocalDb)\\MSSQLLocalDB;Database=MyProject;Trusted_Connection=True"
  4. }
  5. }

运行 Acme.MyProject.DbMigrator 项目,它会负责应用迁移与初始化种子数据. 数据库MyProject将在数据库服务器中创建.

现在一个空的ABP项目已经创建完成! 现在你可以运行项目并且查看网站.

输入用户名 admin 密码 1q2w3E* 登录到网站.

3- 安装模块

文档模块包托管在Nuget上面. 需要有四个包安装到你的应用程序中. 每个包必须安装到相关的项目.

3.1- 使用ABP CLI

建议使用ABP CLI安装模块,在解决方案文件 (.sln) 目录打开 CMD 窗口,运行以下命令:

abp add-module Volo.Docs

3.2- 手动安装

或者你也可以手动安装nuget包到每个项目:

  • 安装Volo.Docs.Domain nuget包到 Acme.MyProject.Domain 项目.

    Install-Package Volo.Docs.Domain

  • 安装Volo.Docs.EntityFrameworkCore nuget包到 Acme.MyProject.EntityFrameworkCore 项目.

    Install-Package Volo.Docs.EntityFrameworkCore

  • 安装Volo.Docs.Application nuget包到 Acme.MyProject.Application 项目.

    Install-Package Volo.Docs.Application

  • 安装Volo.Docs.Web nuget包到 Acme.MyProject.Web 项目. Install-Package Volo.Docs.Web

3.2.1- 添加模块依赖

一个ABP模块必须声明 [DependsOn] attribute 如果它依赖于另一个模块. 每个模块都必须在相关的项目的[DependsOn]Attribute 中添加.

  • 打开 MyProjectDomainModule.cs并且添加 typeof(DocsDomainModule) 如下所示;

    1. [DependsOn(
    2. typeof(DocsDomainModule),
    3. typeof(AbpIdentityDomainModule),
    4. typeof(AbpAuditingModule),
    5. typeof(BackgroundJobsDomainModule),
    6. typeof(AbpAuditLoggingDomainModule)
    7. )]
    8. public class MyProjectDomainModule : AbpModule
    9. {
    10. //...
    11. }
  • 打开 MyProjectEntityFrameworkCoreModule.cs并且添加 typeof(DocsEntityFrameworkCoreModule) 如下所示;

    1. [DependsOn(
    2. typeof(DocsEntityFrameworkCoreModule),
    3. typeof(MyProjectDomainModule),
    4. typeof(AbpIdentityEntityFrameworkCoreModule),
    5. typeof(AbpPermissionManagementEntityFrameworkCoreModule),
    6. typeof(AbpSettingManagementEntityFrameworkCoreModule),
    7. typeof(AbpEntityFrameworkCoreSqlServerModule),
    8. typeof(BackgroundJobsEntityFrameworkCoreModule),
    9. typeof(AbpAuditLoggingEntityFrameworkCoreModule)
    10. )]
    11. public class MyProjectEntityFrameworkCoreModule : AbpModule
    12. {
    13. //...
    14. }
  • 打开 MyProjectApplicationModule.cs并且添加 typeof(DocsApplicationModule) 如下所示;

    1. [DependsOn(
    2. typeof(DocsApplicationModule),
    3. typeof(MyProjectDomainModule),
    4. typeof(AbpIdentityApplicationModule))]
    5. public class MyProjectApplicationModule : AbpModule
    6. {
    7. public override void ConfigureServices(ServiceConfigurationContext context)
    8. {
    9. Configure<PermissionOptions>(options =>
    10. {
    11. options.DefinitionProviders.Add<MyProjectPermissionDefinitionProvider>();
    12. });
    13. Configure<AbpAutoMapperOptions>(options =>
    14. {
    15. options.AddProfile<MyProjectApplicationAutoMapperProfile>();
    16. });
    17. }
    18. }
  • 打开 MyProjectWebModule.cs并且添加 typeof(DocsWebModule) 如下所示;

    1. [DependsOn(
    2. typeof(DocsWebModule),
    3. typeof(MyProjectApplicationModule),
    4. typeof(MyProjectEntityFrameworkCoreModule),
    5. typeof(AbpAutofacModule),
    6. typeof(AbpIdentityWebModule),
    7. typeof(AbpAccountWebModule),
    8. typeof(AbpAspNetCoreMvcUiBasicThemeModule)
    9. )]
    10. public class MyProjectWebModule : AbpModule
    11. {
    12. //...
    13. }
3.2.2- 添加NPM包

打开 package.json 添加 @abp/docs 如下所示:

  1. {
  2. "version": "1.0.0",
  3. "name": "my-app",
  4. "private": true,
  5. "dependencies": {
  6. "@abp/aspnetcore.mvc.ui.theme.basic": "^5.0.0",
  7. "@abp/docs": "^5.0.0"
  8. }
  9. }

然后在 Acme.MyProject.Web 项目目录打开命令行终端运行以下命令:

  1. abp install-libs

4- 数据库集成

4.1- Entity Framework 集成

如果你选择了Entity Framework 做为数据库供应者,你需要配置文档模块. 做以下操作;

  • 打开 MyProjectMigrationsDbContext.cs 并且添加 builder.ConfigureDocs()OnModelCreating() 方法中

    1. public class MyProjectMigrationsDbContext : AbpDbContext<MyProjectMigrationsDbContext>
    2. {
    3. public MyProjectMigrationsDbContext(DbContextOptions<MyProjectMigrationsDbContext> options)
    4. : base(options)
    5. {
    6. }
    7. protected override void OnModelCreating(ModelBuilder builder)
    8. {
    9. base.OnModelCreating(builder);
    10. /* Include modules to your migration db context */
    11. builder.ConfigurePermissionManagement();
    12. builder.ConfigureSettingManagement();
    13. builder.ConfigureBackgroundJobs();
    14. builder.ConfigureAuditLogging();
    15. builder.ConfigureIdentity();
    16. builder.ConfigureIdentityServer();
    17. builder.ConfigureFeatureManagement();
    18. builder.ConfigureTenantManagement();
    19. builder.ConfigureDocs(); //Add this line to configure the Docs Module
    20. /* Configure customizations for entities from the modules included */
    21. builder.Entity<IdentityUser>(b =>
    22. {
    23. b.ConfigureCustomUserProperties();
    24. });
    25. /* Configure your own tables/entities inside the ConfigureQaDoc method */
    26. builder.ConfigureMyProject();
    27. }
    28. }
  • 打开 Visual Studio包管理控制台 选择 Acme.MyProject.EntityFrameworkCore.DbMigrations 做为默认项目. 然后编写以下命令为文档模块添加迁移.

    1. add-migration Added_Docs_Module

    当命令执行成功后 , 你会看到Acme.MyProject.EntityFrameworkCore.DbMigrations\Migrations 目录下有名为 20181221111621_Added_Docs_Module 的迁移文件.

    现在更新数据库. 在 Visual Studio包管理控制台 中执行以下代码. 要确认已 Acme.MyProject.EntityFrameworkCore.DbMigrations 项目设置为默认项目.

    1. update-database

    最后你可以查看数据库中创建的新表,例如你可以看到 DocsProjects 表已经添加到数据库中.

5- 链接文档模块

文档模块的默认路由是;

  1. /Documents

添加文档模块的链接到你的应用程序菜单中;

  • 打开 MyProjectMenuContributor.cs 并且在 ConfigureMainMenuAsync() 方法方法中添加以下代码.

    1. context.Menu.Items.Add(new ApplicationMenuItem("MyProject.Docs", l["Menu:Docs"], "/Documents"));

    最后 MyProjectMenuContributor.cs 有以下内容

    1. private async Task ConfigureMainMenuAsync(MenuConfigurationContext context)
    2. {
    3. var l = context.ServiceProvider.GetRequiredService<IStringLocalizer<MyProjectResource>>();
    4. context.Menu.Items.Insert(0, new ApplicationMenuItem("MyProject.Home", l["Menu:Home"], "/"));
    5. context.Menu.Items.Add(new ApplicationMenuItem("MyProject.Docs", l["Menu:Docs"], "/Documents"));
    6. }

Menu:Docs 关键词是本地化的Key. 要本地化菜单文本, 打开Acme.MyProject.Domain 中的 Localization\MyProject\zh-Hans.json. 添加以下行.

  1. "Menu:Docs": "文档"

最后 zh-Hans.json 有以下内容

  1. {
  2. "culture": "zh-Hans",
  3. "texts": {
  4. "Menu:Home": "首页",
  5. "Welcome": "欢迎",
  6. "LongWelcomeMessage": "欢迎来到该应用程序. 这是一个基于ABP框架的启动项目. 有关更多信息, 请访问 abp.io.",
  7. "Menu:Docs": "文档"
  8. }
  9. }

现在菜单中已经添加了文档模块项. 运行Web应用程序并且在浏览器中打开 http://localhost:YOUR_PORT_NUMBER/documents URL.

你会看到一个警告;

  1. There are no projects yet!

这个警告是正常的,因为我们还没有添加任何项目.

6- 添加文档项目

在数据库中打开 DocsProjects, 并且插入包含以下字段的新记录;

  • Name: 在Web页面上文档的显示名称.
  • ShortName: 在文档URL中使用的友好的简短URL名称.
  • Format: 文档的格式 ( Markdown: md, HTML: html)
  • DefaultDocumentName: 文档的初始页面.
  • NavigationDocumentName: 导航菜单(索引)的文档.
  • MinimumVersion: 显示文档的最低版本. 低于此的版本不会列出.
  • DocumentStoreType: 文档的来源 ( GitHub:GitHub,文件系统FileSystem).
  • ExtraProperties: 序列化的JSON, 它存储所选 DocumentStoreType 的特殊配置.
  • MainWebsiteUrl: 用户单击文档模块页面Logo时跳转的URL.你只需设置为/即可链接到网站根地址.
  • LatestVersionBranchName: 这是GitHub的配置.它是检索文档的分支名称.你可以将其设置为master.

“GitHub” 项目的示例记录

你可以使用 ABP Framework GitHub文档来配置Github文档存储.

  • Name: ABP framework (GitHub)

  • ShortName: abp

  • Format: md

  • DefaultDocumentName: Index

  • NavigationDocumentName: docs-nav.json

  • MinimumVersion: <NULL> (no minimum version)

  • DocumentStoreType: GitHub

  • ExtraProperties:

    1. {"GitHubRootUrl":"https://github.com/abpframework/abp/tree/{version}/docs/zh-Hans/","GitHubAccessToken":"***","GitHubUserAgent":""}

    注意 GitHubAccessToken*** 掩盖. 这是一个私人令牌,你必须从GitHub获取它. 请参阅 https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/

  • MainWebsiteUrl: /

  • LatestVersionBranchName: dev

对于 SQL 数据库,你可以使用下面的 T-SQL 命令将指定的示例插入到 DocsProjects 表中:

  1. INSERT [dbo].[DocsProjects] ([Id], [Name], [ShortName], [Format], [DefaultDocumentName], [NavigationDocumentName], [MinimumVersion], [DocumentStoreType], [ExtraProperties], [MainWebsiteUrl], [LatestVersionBranchName], [ParametersDocumentName]) VALUES (N'12f21123-e08e-4f15-bedb-ae0b2d939658', N'ABP framework (GitHub)', N'abp', N'md', N'Index', N'docs-nav.json', NULL, N'GitHub', N'{"GitHubRootUrl":"https://github.com/abpframework/abp/tree/{version}/docs","GitHubAccessToken":"***","GitHubUserAgent":""}', N'/', N'dev', N'')

请注意,GitHubAccessToken 被屏蔽了.它是一个私人令牌,你必须获得自己的令牌并替换 *** 字符串.

现在你可以运行应用程序并导航到 /Documents.

“FileSystem” 项目的示例记录

你可以使用 ABP Framework GitHub文档来配置你的文件系统存储.

  • Name: ABP framework (FileSystem)

  • ShortName: abp

  • Format: md

  • DefaultDocumentName: Index

  • NavigationDocumentName: docs-nav.json

  • MinimumVersion: <NULL> (no minimum version)

  • DocumentStoreType: FileSystem

  • ExtraProperties:

    1. {"Path":"C:\\Github\\abp\\docs"}

    请注意 Path 必须使用本地docs目录替换. 你可以从https://github.com/abpframework/abp/tree/master/docs获取ABP Framework的文档并且复制到该目录 C:\\Github\\abp\\docs 使其正常工作.

  • MainWebsiteUrl: /

  • LatestVersionBranchName: <NULL>

对于 SQL 数据库,你可以使用下面的 T-SQL 命令将指定的示例插入到 DocsProjects 表中:

  1. INSERT [dbo].[DocsProjects] ([Id], [Name], [ShortName], [Format], [DefaultDocumentName], [NavigationDocumentName], [MinimumVersion], [DocumentStoreType], [ExtraProperties], [MainWebsiteUrl], [LatestVersionBranchName], [ParametersDocumentName]) VALUES (N'12f21123-e08e-4f15-bedb-ae0b2d939659', N'ABP framework (FileSystem)', N'abp', N'md', N'Index', N'docs-nav.json', NULL, N'FileSystem', N'{"Path":"C:\\Github\\abp\\docs"}', N'/', NULL, N'')

添加上面的一个示例项目后运行该应用程序. 在菜单中你会看到文档 链接,点击菜单链接打开文档页面.

到目前为止, 我们已经从abp.io网站创建了一个新的应用程序,并为Docs模块做好准备.

7- 添加一个新文档

在示例项目记录中, 你可以看到 Format 被指定为 md 指的是 Mark Down. 你可以打开下面的链接查看语法;

https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

ABP文档模块可以把MarkDown渲染为HTML.

现在让我们看一下Markdown格式的示例文档.

  1. # This is a header
  2. Welcome to Docs Module.
  3. ## This is a sub header
  4. [This is a link](https://abp.io)
  5. ![This is an image](https://abp.io/assets/my-image.png)
  6. ## This is a code block
  7. ```csharp
  8. public class Person
  9. {
  10. public string Name { get; set; }
  11. public string Address { get; set; }
  12. }
  13. ```

你可以使用 ABP Framework 的文档做为示例:

https://github.com/abpframework/abp/blob/master/docs/zh-Hans/

有条件的部分功能(使用Scriban)

文档模块使用Scriban有条件的显示或隐藏文档的某些部分. 使用该功能你需要为每一种语言创建一个JSON文件做为参数文档. 它包含所有键值以及它们的显示名称.

例如 en/docs-params.json:

  1. {
  2. "parameters": [{
  3. "name": "UI",
  4. "displayName": "UI",
  5. "values": {
  6. "MVC": "MVC / Razor Pages",
  7. "NG": "Angular"
  8. }
  9. },
  10. {
  11. "name": "DB",
  12. "displayName": "Database",
  13. "values": {
  14. "EF": "Entity Framework Core",
  15. "Mongo": "MongoDB"
  16. }
  17. },
  18. {
  19. "name": "Tiered",
  20. "displayName": "Tiered",
  21. "values": {
  22. "No": "Not Tiered",
  23. "Yes": "Tiered"
  24. }
  25. }]
  26. }

因为并不是项目中的每个文档都有章节或者不需要所有的参数,你必须声明哪些参数将用于对文档进行分段,在文档的任何地方都可以使用JSON块.

例如 Getting-Started.md:

  1. .....
  2. ........

这个部分会在渲染时自动删除.前提是这些键值必须与参数文档中的键值匹配.

Interface

现在你可以使用 Scriban 语法在文档中创建章节.

示例 :

还可以在文本中使用变量,在其键中添加 _Value 后缀:

  1. This document assumes that you prefer to use **** as the UI framework and **** as the database provider.

如果你想要得到的当前文档的语言或版本,可以使用预定义的 Document_Language_CodeDOCUMENT_VERSION 键(这对于创建重定向到另一个地区中另一个文档系统的链接很有用).


重要提示: Scriban 的语法是 “ and “. 如果要在文档(如Angular文档)中使用转义,则必须使用转义块. 参阅 Scriban文档 了解更多信息.

8- 创建文档导航

导航文档是文档页面的主菜单. 它位于页面的左侧,是一个JSON 文件. 请查看以下示例导航文档以了解结构.

  1. {
  2. "items":[
  3. {
  4. "text":"Sample Menu Item - 1",
  5. "items":[
  6. {
  7. "text":"Sample Menu Item - 1.1",
  8. "items":[
  9. {
  10. "text":"Sample Menu Item - 1.1.1",
  11. "path":"SampleMenuItem_1_1_1.md"
  12. }
  13. ]
  14. },
  15. {
  16. "text":"Sample Menu Item - 1.2",
  17. "items":[
  18. {
  19. "text":"Sample Menu Item - 1.2.1",
  20. "path":"SampleMenuItem_1_2_1.md"
  21. },
  22. {
  23. "text":"Sample Menu Item - 1.2.2",
  24. "path":"SampleMenuItem_1_2_2.md"
  25. }
  26. ]
  27. }
  28. ]
  29. },
  30. {
  31. "text":"Sample Menu Item - 2",
  32. "items":[
  33. {
  34. "text":"Sample Menu Item - 2.1",
  35. "items":[
  36. {
  37. "text":"Sample Menu Item - 2.1.1",
  38. "path":"SampleMenuItem_2_1_1.md"
  39. }
  40. ]
  41. }
  42. ]
  43. }
  44. ]
  45. }

上面的示例 JSON 文件将下面的导航菜单呈现为 HTML .

Navigation menu

最后,为你的项目添加了一个新的Docs模块, 该模块由GitHub提供.

全文搜索(Elastic Search)

文档模块支持使用Elastic Search对内容进行全文搜索. 默认没有启用, 你可以配置DocsElasticSearchOptions启用它.

  1. Configure<DocsElasticSearchOptions>(options =>
  2. {
  3. options.Enable = true;
  4. options.IndexName = "your_index_name"; //default IndexName is abp_documents
  5. });

应用程序启动后如果Index不存在则会自动创建Index.

DefaultElasticClientProvider负责创建IElasticClient, 默认情况下它会从IConfiguration中读取Elastic Search的Url. 如果你的 IElasticClient 需要其它配置请使用重写 IElasticClientProvider 服务并在依赖注入系统中替换它.

  1. {
  2. "ElasticSearch": {
  3. "Url": "http://localhost:9200"
  4. }
  5. }

下一步

文档模块也可以做为独立的应用程序. 查看 VoloDocs.