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(Gitlab的Wiki引擎)不支持HTML.由于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文档提供服务的网络服务器，让您的构建服务器在每次构建后上传最新版本，然后每天调用它即可.

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存储库中还是一个好主意，因为您可以免费获得压缩，并且使用git pull比使用任何压缩要好得多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屋！