Gitlab 和 HTML 文档 [英] Gitlab and HTML documentation

问题描述

我的开发环境由 Git 存储库、GitLab 存储库管理器和 Jenkins 组成.在构建过程中，使用 Doxygen 生成 HTML 格式的文档.

My development environment consists of Git repository, GitLab repository manager and Jenkins. During build process a documentation is generated with Doxygen in HTML format.

是否可以将该文档存储在 GitLab 项目的 wiki 上?我知道 Gollum 不支持 HTML，它是 Gitlab 的 wiki 引擎.由于 HTML 文件中的内部链接指向其他 HTML 文件，因此将 HTML 转换为 Markdown 并不令人满意.

Is it possible to store that documentation on GitLab project's wiki? I know that HTML is not supported in Gollum, which is the Gitlab's wiki engine. Converting HTML to Markdown is not satisfactory because of internal links in HTML files that point to other HTML files.

我是否应该将文档存储在单独的 wiki 中，并且只提交 GitLab 项目 wiki 的链接?

Should I store documentation in a separate wiki instead and only commit a link to GitLab project wiki?

推荐答案

我想答案取决于您使用 HTML 文档的目的以及分发它的数量.

I guess the answer depends on what you use your HTML documentation for and how much you distribute it.

首先，你使用的是哪个版本的Gitlab?

First of all, which version of Gitlab are you using ?

1. 如果您的开发人员只能访问(也就是私有文档)，那么在 Gitlab >= 8.1.2 上有一个名为 External 的服务Wiki 允许您将项目的 Wiki 链接替换为您选择的任何 URL.只需设置一个为您的 html 文档提供服务的 Web 服务器，让您的构建服务器在每次构建后上传最新版本并收工.

1. If it is only for your developers to get access to (aka these are private documents), then on Gitlab >= 8.1.2 there is a service called External Wiki that allows you to substitute the Wiki link of the project by any URL of your choice. Just set up a web server serving your html documentation, have your build server upload the newest version after each build and call it a day.

如果您的文档是您想要进行版本控制和分发的代码，那么就这样做.

If your documentation is a code that you want to version control and distribute, then do so.

无论您选择 1. 还是 2.，将整个文档放在单独的 git 存储库中仍然是一个好主意，因为您可以免费获得压缩并使用 gitpull 比使用任何 rsync 来同步任何本地或远程目录要好得多.然后只需设置 shell 脚本或 git hooks 自动为您完成所有工作；在提交或构建时.

Whether you go for 1. or 2., it is still a good idea to have a the whole documentation in a separate git repository, because you get compression for free and using git pull is much better than using any rsync to synchronise any local or remote directories. Then is just a matter of setting up shell script or git hooks to automatically do all of it for you; either at commit or build time.

希望这会有所帮助！

这篇关于Gitlab 和 HTML 文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！