基于Read the Docs的离线文档服务器搭建

1 需求来源

在离线的网络环境中开发，难免会遇到查询文档的时候。为了避免在离线和有线的网络环境中频繁切换，决定在局域网搭建Read the Docs。以下是搭建过程中的记录。

2 方案

Docker + Sphinx + Read the Docs
注：以下为只是为了从docker基础镜像开始熟悉流程。实际上可以直接使用docker hub中的镜像

docker pull readthedocs/build:latest

3 开始搭建

3.1 获取centos docker镜像

这里我选择了centos7.9:2009这个版本

docker pull centos:centos7.9.2009

3.2 python版本的安装

• 下载需要的python版本，这里选择了3.7.3

mkdir -p /var/python3
cd /var/python3
wget https://www.python.org/ftp/python/3.7.3/Python-3.7.3.tgz

• 安装python

# 安装前的准备
yum -y install zlib-devel bzip2-devel openssl-devel ncurses-devel sqlite-devel readline-devel tk-devel gcc libffi-devel

tar -zxf Python-3.7.3.tgz

cd Python-3.7.3
./configure --prefix=/usr/local/python3.7
make && make install
# 编译完成

• 替换python2

因为系统中自带了python2，这里替换python2

ln -sf /usr/local/python3.7/bin/python3.7 /usr/bin/python
ln -sf /usr/local/python3.7/bin/pip3 /usr/bin/pip

# 因为系统有的脚本还是需要python2的，这里手动改一下有的脚本的支持
vim /usr/bin/yum
vim /usr/libexec/urlgrabber-ext-down
# 将python改为/usr/bin/python2

• 查看python版本

> python
Python 3.7.3 (default, Apr  1 2022, 14:59:06)
[GCC 4.8.5 20150623 (Red Hat 4.8.5-44)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
# 说明python3安装完成

3.3 使用pip安装sphinx

pip install sphinx sphinx-autobuild sphinx_rtd_theme
ln -sf /usr/local/python3.7/bin/sphinx-* /usr/bin

3.4 安装nginx

提供文档访问

# 安装依赖
yum install -y gcc glibc gcc-c++ prce-devel openssl-devel pcre-devel

# 下载需要的nginx版本
wget http://nginx.org/download/nginx-1.19.9.tar.gz

# 安装依赖
yum install -y gcc glibc gcc-c++ prce-devel openssl-devel pcre-devel

# 添加用户
useradd -s /sbin/nologin www -M

# 安装nginx
tar zxvf nginx-1.19.9.tar.gz
cd nginx-1.19.9
./configure --prefix=/usr/local/nginx-1.19.9 --user=www --group=www --with-http_ssl_module --with-http_stub_status_module
make && make install

# 为了方便使用将nginx软链接出来
ln -sf /usr/local/nginx-1.19.9/sbin/nginx  /usr/bin/nginx

至此，Read the Doc的容器基本配置完了，可以将容器commit，以便后续多个doc的搭建。

3.5 使用

这里以dpdk的一个版本为例

• 将下载好的dpdk源码拷贝至Read the Docs容器中，记得开启端口映射

docker run -d -p 8080:80 readthedpdk:latest init

• 进入doc/guides目录

> ls
bbdevs         contributing   eventdevs      howto          mempool        platform       rel_notes      tools
compressdevs   cryptodevs     faq            index.rst      meson.build    prog_guide     sample_app_ug  windows_gsg
conf.py        custom.css     freebsd_gsg    linux_gsg      nics           rawdevs        testpmd_app_ug

• 使用sphinx-build构建

sphinx-build -b html /var/dpdk-19.11/doc/guides build

• 修改nginx.conf
  
  这里将上一步build的出来的目录更新上去
• 启动nginx
  nginx

3.6 可以在宿主机上看效果啦

localhost:8080