OpenFOAM-源码文档的生成与发布

创建时间: 2020-03-13 11:33:30
摘要: 总结OpenFOAM源码中自带的文档使用方法。

1. 前言

最近开始学习OpenFOAM，最直接的资料就是源码中自带的doc。该文档可以直接在官网查看，但是国内访问OF官网太慢，影响正常使用。更好的方法是使用doxygen工具在本地生成html形式的文档，然后用浏览器打开（或者将其挂载到服务器上，可供局域网内的设备浏览）。

本文基于Ubuntu18.04，针对两个版本的OpenFOAM-v1812和OpenFOAM-6来比较说明不同版本如何生成文档；然后介绍文档中图例的使用。

2. 文档生成

参考源码中doc/Doxygen/README.html文件夹中的说明。

2.1. 安装相关工具

doxygen用来生成文档，其中会用到graphviz来生成图例（即dot图），因此要保证环境中存在这两个工具。

sudo apt-get update
sudo apt-get install doxygen graphviz

2.2. 配置

配置Doxyfile，使之能自动生成文档中的Header、Footer、以及Stylesheet(样式表)：

doxygen -w html header.html footer.html 

2.3. 运行Doxygen

切换到$WM_PROJECT_DIR/doc/Doxygen文件夹，运行：

./Allwmake

结果会在WM_PROJECT_DIR/doc/Doxygen/html目录中保存生成的OpenFOAM的源码文档。使用下面的命令在浏览器中查看，以firefox为例(若没添加浏览器环境变量，就使用绝对路径指定浏览器)：

firefox $WM_PROJECT_DIR/doc/Doxygen/html/index.html

3. nginx配置

3.1. 使用默认端口80

大致配置步骤如下：

使用sudo apt install nginx安装nginx
编辑/etc/nginx/sites-available/default，修改server中root指定的地址为html文件夹路径
编辑/etc/nginx/nginx.conf中的user值为root
重启nginx：sudo /etc/init.d/nginx restart

之后便可以使用同局域网内的设备访问该网站了。比如在本地浏览器中访问：localhost或127.0.0.1；在局域网中(假设挂载网页的设备ip为192.168.99.129)使用iPad浏览器访问192.168.99.129。

3.2. 使用多端口配置不同文档访问路径

若只研究一个版本的文档，则可跳过下面的内容。有时候可能需要对比多版本文档，或者80端口已有其他服务占用，如个人网站，这时候就需要在/etc/nginx/sites-available/default中使用多端口配置来发布不同类型的网站。

参考SSgeek的博客：Nginx配置基于多域名、端口、IP的虚拟主机来配置。

这里针对两个版本的OF源码文档来说明，最终的配置如下（这里我将Doxygen编译得到的html文件夹移动到了其他位置）：

server {
        listen 80 default_server;
        root /home/yz/OpenFOAM/DOC_of_v1812/html;
        index index.html;
        server_name localhost;
        location / {
                try_files $uri $uri/ =404;
        }
}

server {
        listen 81 ;
        root /home/yz/OpenFOAM/DOC_of_6/html;
        index index.html;
        server_name localhost;
        location / {
                try_files $uri $uri/ =404;
        }
}

效果图如下（通常80端口是网站的默认端口，可以不指定；81端口需要显式指定）：