安装PCL点云库官方文档至本地计算机

1. 引言

在学习和日后使用PCL的过程频繁翻阅PCL文档是必不可少的，但是由于PCL目前挂载在GitHub上，而目前中国大陆由于某些不可抗力导致访问该网站速度极慢，如果可以将文档下载到本地，使用将会及其方便。而其官方文档也有教你怎么生成本地文档，但是由于该教程针对1.7的文档，没有更新到现在官网的1.11，且安装过程中会产生很多问题。该文章将依据此教程进行重新梳理。

2. 软件配置

1. Ubuntu 16.04 LTS
2. python 2.7
3. pip 20.2.1
   若生成PCL 1.11.0文档，则使用如下组合
4. sphinx 1.8.5
5. sphinxcontrib-doxylink 1.4（太新会报错）
   若生成PCL 1.7文档，则使用如下组合
6. sphinx 1.7
7. sphinxcontrib-doxylink 1.0

3. 安装依赖

1. 安装依赖软件
   安装doxygen、graphviz、python-pip，这里面有些您可能已经安装。

sudo apt-get install doxygen graphviz python-pip

这里如果按照官网教程加上“sphinx3”进行安装，会报如下错误。猜测可能是因为新的sphinx已经改用pip进行安装，故无法使用apt-get安装

E: 无法定位软件包 sphinx3

2. 安装sphinx
   这里我们使用国内的源进行安装，最后的==1.8.5指定安装版本，可更改。

sudo pip --trusted-host pypi.douban.com install -i http://pypi.douban.com/simple -U sphinx==1.8.5

否则如果按照sphix官方文档使用“sudo pip install -U sphinx”进行安装，pip默认会从python官网进行下载，速度会让所有人感动，甚至会出现连接超时的错误，如下所示

raise ReadTimeoutError(self._pool, None, "Read timed out.")

3. 安装sphinxcontrib-doxylink
   同样使用国内源。

sudo pip --trusted-host pypi.douban.com install -i http://pypi.douban.com/simple sphinxcontrib-doxylink==1.4

上面语句中最后的“==1.4”是为了控制安装版本，否则后面使用sphinx-build命令将rst文件编译为html文件时会报如下错误，看文件地址猜测跟sphinxcontrib-doxylink版本太新与python2.7不兼容有关，经过测试发现1.4可以使用。

抛出异常：
  File "/usr/local/lib/python2.7/dist-packages/sphinx/registry.py", line 472, in load_extension
    mod = __import__(extname, None, None, ['setup'])
  File "/usr/local/lib/python2.7/dist-packages/sphinxcontrib/doxylink/doxylink.py", line 63
    def __getitem__(self, arglist: str) -> Entry:
                                 ^
SyntaxError: invalid syntax

但是在安装sphinxcontrib-doxylink过程中，如果您的pip版本低，有可能会报出如下警告

You are using pip version 8.1.1, however version 20.2.1 is available.
You should consider upgrading via the 'pip install --upgrade pip' command.

也有可能会报错

      File "/tmp/pip-build-bngg4D/Sphinx/sphinx/deprecation.py", line 32
        def deprecated_alias(modname: str, objects: Dict[str, object],
                                    ^
    SyntaxError: invalid syntax
    
    ----------------------------------------
Command "python setup.py egg_info" failed with error code 1 in /tmp/pip-build-bngg4D/Sphinx/

直接按照提示pip install --upgrade pip进行升级可能会无效，此时需要将pip卸载然后再安装

sudo apt remove python-pip #卸载
sudo python -m pip --trusted-host pypi.douban.com install -i http://pypi.douban.com/simple --upgrade --force pip #安装升级

如果出现Successfully installed pip-20.2.1说明安装升级完成。
同时，也有可能会遇到如下问题

The directory '/home/bit202/.cache/pip/http' or its parent directory is not owned by the current user and the cache has been disabled. Please check the permissions and owner of that directory. If executing pip with sudo, you may want sudo's -H flag.
The directory '/home/bit202/.cache/pip' or its parent directory is not owned by the current user and caching wheels has been disabled. check the permissions and owner of that directory. If executing pip with sudo, you may want sudo's -H flag.

该问题可能并不会影响安装，其产生的原因打印内容已经说明，是因为上面两个路径或者其父不被当前用户拥有，可以使用如下方法将其父路径改变拥有性。

sudo chown -R root ~/.cache/

然后使用下面指令你就可以正常访问该目录

sudo chmod 755 ~/.cache -R

也有可能会出现如下错误，原因可能为python版本与pip版本不兼容

Traceback (most recent call last):
File "/home/myuser/.local/bin/pip", line 7, in <module>
from pip._internal import main
ImportError: No module named 'pip._internal'

可以使用如下方法解决，更改对应目录下的python脚本内容即可

cd /usr/local/bin
sudo gedit pip

将语句from pip._internal import main改为from pip import main。
解决以上问题之后再运行安装指令，即可正常安装，如果不小心安装版本不对，可以使用下面指令进行卸载

pip uninstall <软件名>

3. rst文档编译

该部分主要参考Dijkstra__转载的一篇文章和XiaO天的一篇文章

1. 下载pcl包
   笔者使用的是pcl1.11.0，去其GitHub仓库下载源码，并解压。
2. 安装sphinx_rtd_theme

sudo pip --trusted-host pypi.douban.com install -i http://pypi.douban.com/simple sphinx_rtd_theme

若跳过此步骤，直接进行下一步“文档编译”，有可能报错

Theme error:
sphinx_rtd_theme is no longer a hard dependency since version 1.4.0. Please install it manually.(pip install sphinx_rtd_theme)

3. 文档编译
   pcl包中的doc文件夹中即为手册的rst文件工程。
   终端切换路径到pcl包下的…/doc/tutorials/content，进行编译教程手册

cd /<pcl包>/doc/tutorials/content
sphinx-build -b html ./ ./build/

编译高级手册

cd /<pcl包>/doc/advanced/content
sphinx-build -b html ./ ./build/

4. 打开文档
   在以上两个路径下的build问价夹下即产生了对应html文档，找到其中的index.html双击打开就看到文档的首页了。接下来将文档拷贝到自己想要放置的路径，在需要时即可快速在本地查看。

4. 安装和配置Apache

1. 安装Apache和php
   下面是官方指令，但是运行会报错

$ sudo apt-get install apache2 php5 libapache2-mod-php5
…
E: 软件包 php5 没有可安装候选
E: 软件包 libapache2-mod-php5 没有可安装候选

这是因为目前（2020.08.20）php版本已经升级到了7.0，所以需要将上面指令更换为下面这条指令。不过你也可以在输入php之后安tab键，系统将会显示备选软件，选一个合适的即可。

$ sudo apt-get install apache2 php libapache2-mod-php

2. 编辑apache默认网址
   使用gedit打开

$ sudo gedit /etc/apache2/sites-available/000-default.conf

将下面这一行的目录

DocumentRoot /var/www/html

改为你的index所在的安装目录，或你自己存放index的目录

DocumentRoot /usr/local/share/doc/pcl-1.7/html/

3. 更改apache路径选项
   打开对应配置文件并将光标移动到153行

$ sudo gedit +153 /etc/apache2/apache2.conf

使用下面的语句替换153行两个<Directory />所夹的内容，保存

<Directory />
    #Options FollowSymLinks
    Options Indexes FollowSymLinks Includes ExecCGI
    AllowOverride All
    Order deny,allow
    Allow from all
</Directory>

4. 重启Apache，打开localhost搜索框应该可以正常工作了

$ sudo /etc/init.d/apache2 restart
$ firefox localhost

记得点赞，让我知道我帮助了多少人。