sphinx构建html文档库

1、初识sphinx

        Sphinx 是一种文档工具，基于reStructuredText / rst格式编写文档, 有着众多的插件和良好的生态，可以生成高质量的出版级别的文档。

        目前，很多大公司，尤其是AI相关的大公司，都采用sphinx构建自己的文档系统。比如，寒武纪、nvidia、pytorch等等。

        具体效果可以查看以下寒武纪和NV的官网。

        寒武纪文档系统

        nvidia文档系统

2、sphinx环境构建

        sphinx的组件很多。功能也很强大，以下是我目前使用的一些基础的组件和主题。

#!/bin/bash

# 安装pip3
sudo dnf install python3-pip

# 安装markdown
sudo pip3 install markdown

# 安装sphinx相关工具
sudo pip3 install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark sphinx-markdown-tables
sudo pip3 install sphinx_panels
sudo pip3 install sphinx_copybutton

# 安装sphinx主题
sudo pip3 install pytorch_sphinx_theme

# 安装myst，该工具实现了对markdown语法的解析
sudo pip3 install myst_parser

# 安装sphinx
sudo pip3 install -U sphinx

# 查看版本号
sphinx-build –version

3、构建个人sphinx工程

3.1 通过标准指令构建工程

        通过sphinx-quickstart 指令，你可以构建一个标准的sphinx工程。

        执行完sphinx-quickstart ​​​​​​​指令后，在指定的project release路径下，你会得到一个原生的sphinx工程。

3.2 个性化配置文件conf.py

        sphinx的功能太丰富了，所以我们不可能使用所有的功能，我们只需要筛选我们必要的一些功能点即可。conf.py中，实现了对sphinx工具进行配置。经过筛选之后，目前保留的几个配置内容如下：

step 1. 导入必要的工具

import sys
from os.path import abspath, dirname

import os
from os import path
import re
# import sys
import pkgutil

from sphinx import ext
import sphinx_rtd_theme
import pytorch_sphinx_theme

from docutils import nodes
from sphinx.util.docfields import TypedField
from sphinx import addnodes
from sphinx import writers
from sphinx import templates
import sphinx.ext.doctest

step 2. 执行source的位置

        source就是文档生成的素材，比如可以是markdown文本，可以是rst格式的文本。

# source code directory, relative to this file, for sphinx-autobuild
sys.path.insert(0, os.path.abspath('../..'))

step 3. 添加必要的组件

extensions = [
        'sphinx.ext.autodoc',
		'sphinx.ext.autosummary',
		'sphinx.ext.doctest',
		'sphinx.ext.intersphinx',
		'sphinx.ext.todo',
		'sphinx.ext.coverage',
		'sphinx.ext.napoleon',
		'sphinx.ext.viewcode',
		'sphinx.ext.autosectionlabel',
		'sphinx_copybutton',
		'sphinx_panels',
		'myst_parser',
]

step 4. 选择语言和主题

templates_path = ['_templates']
exclude_patterns = []

language = 'English'

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'sphinx_rtd_theme'

html_static_path = ['_static']

step 5. 个性化信息

project = 'show_docs_test'
copyright = '2024, GG'
author = 'GG'
version = 'v1.0'
release = 'master'

3.3 个性化索引文件index.rst

.. show_test documentation master file, created by
   sphinx-quickstart on Fri Apr 19 12:27:56 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

show_test toctree
=====================================

.. toctree::
   :maxdepth: 1
   :caption: markdown document test
   
   markdown/markdown
   
.. toctree::
   :maxdepth: 1
   :caption: markdown reference test
   
   markdown/mkref

.. toctree::
   :maxdepth: 5
   :caption: rst document test

   pytorchtest/amp_examples
   
   
Indices and tables
==================

        当然，你的source路径下，也应该要存在markdown/markdown.md，markdown/mkref.md，pytorchtest/amp_examples.rst

        markdown路径下的是提供的markdown语法写的参考例子。

        pytorchtest下提供的是从pytorch开源代码中提取的rst语法写的参考例子。

3.4 生成html

        在工程路径下执行，sphinx-build source/ build/。则会在build路径下，生成最终产物，我们打开index.html，最终展示效果如下。

4、基于httpd实现对服务器静态网页的访问

        执行以下指令，进行httpd的安装，以及打开httpd服务。

#!/bin/bash

sudo yum install -y httpd
sudo systemctl stop firewalld.service
sudo systemctl status firewalld.service
sudo systemctl enable httpd
sudo systemctl start httpd
sudo systemctl status httpd.service

        将我们上面生成的build路径拷贝到httpd的指定路径下。

sudo cp -r build/ /var/www/html/

        然后通过 http://ip_addr/build/index.html就可以访问服务器端的静态页面了。ip_addr替换成你的sphinx服务器的ip地址。

        本文已提供完整的sphinx完成参考例程。如有需要，可自行下载参考使用。

以下是参考文献。如有侵权请告知，会及时删除。谢谢

参考文献：

Sphinx工具介绍页面

Sphinx版本下载页面

linux使用apache发布静态html网页