Ubuntu 20.04 安装 Sphinx-Doc

Sphinx 是一个功能强大的文档生成器工具,可让我们创建智能且美观的文档。 它是用 python 编写的,基于 jinja 模板。 Sphinx 具有许多功能,可以更轻松地生成网页、可打印的 PDF 和 ePub 文档。

在这篇文章中,我们将向我们展示 Ubuntu 20.04 上安装 Sphinx-Doc。

先决条件

  • 云平台上的全新 Ubuntu 20.04 服务器
  • 在我们的服务器上配置的 root 密码

第 1 步 – 创建 云服务器

首先,登录到我们的 云服务器。 创建一个新服务器,选择 Ubuntu 20.04 作为至少 2GB RAM 的操作系统。 通过 SSH 连接到我们的云服务器并使用页面顶部突出显示的凭据登录。

登录到 Ubuntu 20.04 服务器后,运行以下命令以使用最新的可用软件包更新基本系统。

apt-get update -y

第 2 步 – 安装所需的依赖项

Sphinx-Doc 是用 Python 编写的,因此我们需要将 Python 模块和 Apache 服务器安装到我们的系统中。 我们可以使用以下命令安装所有这些:

apt-get install python3-pip python3-dev python3-setuptools apache2 -y

安装完所有软件包后,使用以下命令将 pip 更新到最新版本:

pip3 install --upgrade pip

第 3 步 – 安装 Sphinx-Doc

接下来,我们可以使用 pip 命令安装 Sphinx-Doc,如下所示:

pip3 install sphinx

安装完成后,我们应该得到以下输出:

安装收集的包:MarkupSafe、Jinja2、sphinxcontrib-jsmath、Pygments、sphinxcontrib-devhelp、docutils、imagesize、snowballstemmer、alabaster、sphinxcontrib-serializinghtml、sphinxcontrib-htmlhelp、pytz、babel、sphinxcontrib-applehelp、pyparsing、包装、sphinxcontrib-qthelp、狮身人面像
成功安装 Jinja2-2.11.3 MarkupSafe-1.1.1 Pygments-2.8.1 alabaster-0.7.12 babel-2.9.0 docutils-0.16 imagesize-1.2.0 Packaging-20.9 pyparsing-2.4.7 pytz-2021.1 snowballstemmer-2.1。 0 sphinx-3.5.3 sphinxcontrib-applehelp-1.0.2 sphinxcontrib-devhelp-1.0.2 sphinxcontrib-htmlhelp-1.0.3 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-1.0.3 sphinxcontrib-serializinghtml-1.1.4

第 4 步 – 配置 Sphinx-Doc

接下来,将目录更改为 Apache 文档根目录并运行 Sphinx-Doc 设置脚本。

cd /var/www/html/
sphinx-quickstart

我们将被要求提供我们的项目名称、作者姓名和项目版本,如下所示:

Welcome to the Sphinx 3.5.3 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

We have two options for placing the build directory for Sphinx output.
Either, we use a directory "_build" within the root path, or we separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: n

The project name will occur in several places in the built documentation.
> Project name: myapp
> Author name(s): admin
> Project release []: 20.04

If the documents are to be written in a language other than English,
we can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: 

Creating file /var/www/html/conf.py.
Creating file /var/www/html/index.rst.
Creating file /var/www/html/Makefile.
Creating file /var/www/html/make.bat.

Finished: An initial directory structure has been created.

We should now populate wer master file /var/www/html/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

接下来,运行以下命令以生成静态 HTML 文件:

make html

我们应该得到以下输出:

Running Sphinx v3.5.3
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                                                
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                 
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

上述命令将在 /var/www/html/_build/html/index.html 处生成一个 HTML 文件。

第 5 步 – 为 Sphinx-Doc 配置 Apache

接下来,我们需要编辑 Apache 默认虚拟主机配置文件并定义 HTML 文件的路径。

nano /etc/apache2/sites-available/000-default.conf

找到以下留置权:

DocumentRoot /var/www/html/

并且,将其替换为以下行:

DocumentRoot /var/www/html/_build/html/

保存并关闭文件,然后重新启动 Apache 服务以应用更改。

systemctl restart apache2

第 6 步 – 访问 Sphinx-Doc

现在,打开我们的 Web 浏览器并使用 URL http://wer-server-ip 访问 Sphinx-Doc。 我们应该看到以下页面:

恭喜! 我们已经在 Ubuntu 20.04 服务器上成功安装了 Sphinx-Doc。 我们现在可以将 Sphinx-Doc 用于任何文档项目,包括来自 的专用服务器上的一个。

© 版权声明
THE END
喜欢就支持一下吧
点赞13 分享
评论 抢沙发

请登录后发表评论