400-860-6160

技术资料

专业 • 热情 • 信任 • 拥抱变化

聊一聊集群文档管理小帮手

时间:2020-12-12 16:27:21 浏览次数: 分类:技术资料

大家好,“Geeki说”时间又到了!掐指一算,每一个和集群打交道的工程师们电脑里最重要的文件资料排行前三名一定有“集群文档”。没错,就是大家辛辛苦苦忙了大半个月甚至忙了更久的劳动成果!这一期,就让我们来分享一下面对数量庞大、需要不断更新的集群文档,奥工小分队有什么管理的好办法吧!


1.png 

 

01/静态页面需求

 

一个高性能集群从规划实施到部署验收完成,需要输出大量各种各样的文档,其中包括部署实施前的实施规划、实施计划;部署实施中的实施报告、测试报告;部署实施结束后的验收文档、使用手册等等。

 

2.png 

 

奥工小分队队员的电脑里可以说塞满了各式文档,我们在实施部署过程中会将每个客户的文件资料细心整理,并在验收后把文档打包交给客户。

 

大部分文档在验收完成后内容是固定不会变动的,但是对于用户集群的使用手册等文档,难免会随着集群的使用变化而出现一些变动(比如ip的修改、功能的调整等)。针对这种情况,一款在线可以解决用户手册查找问题使用手册就是非常棒的“小帮手”了!

 

那么该选择一款什么样的在线文档输出方式呢?奥工小分队千挑万选“相中”的一款静态网页方案就可以满足上述需要——MkDocs,它的使用改变了以往通过“邮件”“微信群”等滞后的文档传输方式,实现了在线输出和实时修改,给予了用户更好的使用体验。

 

3.png 

MkDocs页面展示)

 

02/MkDocs为何物?

 

MkDocs 是一个简单、快捷、几乎完美的静态站点生成器,是奥工小分用来创建说明文档的有力工具,目前有五大优点和大家展示一下:

 

①任意托管:构建纯静态的HTML网站,可以托管到 GitHub pages、 Amazon S3 等任意地方;

 

②大量主题:除了有内置主题备选外,还可以定制构建自己的主题;

 

③及时预览:内置开发服务器允许在撰写时即时预览文档并在保存更改时自动加载更新;

 

④易于配置:通过一些简单的自定义和插件安装,项目文档可以变成你想要的样子;

 

⑤门槛较低:只要熟悉Markdown页面规则即可,不需要任何前后端代码能力。

 

 

说了这么多优点,来看点实际的,MkDoce中文文档页面展示▼▼▼

 

4.png 

PSMkDocs 官方中文文档就是使用的自家的内置主题之一——mkdocs静态页面方式。

 

 

03/页面使用规则

 

说到这,大家一定跃跃欲试,很关心页面使用规则吧。对于MkDocs的页面规则,使用者可能不仅需要参见下MkDocs的官方文档,还需要参考下 Markdown页面规则定义方式。

 

Markdown是什么?和MkDocs有什么关系呢?简单来说Markdown是一种轻量级标记语言,它允许人们使用易读易写的纯文本格式编写文档。MkDocs页面正完全依赖于Markdown页面输出模式以便形成易于阅读、浏览的方式,但是Markdown的文档书写方式的确也令很多初学者感到些许不适应……没关系,奥工小分队经验之谈告诉你“只要配合git仓库的方式”就可以轻松有效地解决这类问题。现有的git托管网站对Markdown规则做了很好的适配,可以在网页上直接修改,实现边改边看;或者使用现有的cs工具来书写Markdown页面然后同步git仓库或者上传服务器本地的方式去实现。奥工小分队比较熟悉Markdown规则,习惯使用比较“土”的一种方式——直接服务器本地文本修改,简单又快捷!

 

 

04/MkDocs的安装

 

MkDocs的安装比较简单,就四步:

①首先需要一个python环境:miniconda或者anaconda

②配置好环境后使用pip 安装 mkdocs:

5.png 

③开始生成第一个在线文档:

6.png 

④启动服务:mkdocs serve

7.png 

启动后自动会得到一个地址,访问该地址即可打开页面。

 

05/编辑页面

 

安装完成后,开始添加内容。针对安装生成的project项目中有关mkdocs.yml的定义,该文件定义的目录结构可以在docs文件夹中定义的文件/文件夹来设置文档章节,新建各章节的md文件就可以将各章节的内容区分开来编辑。

 

话不多说,直接给出奥工小分队维护的网页目录结构:

8.png 

 

相应的页面内容修改完成后,即可直接在浏览器中查看到所共享的内容,如果后期内容出现修改,页面可以实时更新,客户可以第一时间得到最新内容。

 

MkDocs凭借低门槛、实时更新的优势得到了奥工小分队的青睐,但MkDocs并不是集群文档管理的唯一选择,还有其他的静态网站生成器各有优劣,这里不多加赘述啦!本期到此为止,下期会分享些什么呢?请期待吧!


咨询热线: 400-860-6160

公司邮箱: hwclould@ongineer.cn /og@ongineer.cn

公司地址: 南京市雨花台区锦绣街5号绿地之窗C5座1218室

企业文化

专业 / 热情 / 信任 / 拥抱变化

价值观

成就客户 成长自己