docs.cloud-atlas.io 文档的sphinx

2024年3月,我启动新的文档撰写项目 cloud-atlas-io/docs 作为个人数据中心项目的文档。这个文档项目将继续采用 Sphinx docs ,同时我将实践:

初始化

  • 安装Sphinx工作环境(这里借用了RTD的themes安装命令,对于使用其他theme,可以忽略 sphinx_rtd_theme 安装命令行:

通过virtualenv的Python环境安装sphinx doc(请忽略 sphinx_rtd_theme )
pip install sphinx
pip install sphinx_rtd_theme
pip install sphinxnotes-strike

# 支持视频、YouTube和中文搜索,安装组件和配置
pip install sphinxcontrib-video
pip install sphinxcontrib-youtube
pip install jieba
  • 安装 openstackdocstheme 风格:

安装 openstackdocstheme 风格
pip install openstackdocstheme
  • 初始化项目:

初始化sphinx文档
# 在项目目录下执行
sphinx-quickstart

备注

我的文档项目初始化设置采用了 sourcebuild 分离的设置

  • 修改 conf.py 配置,启用 openstackdocs

修订 conf.py 启用 openstackdocstheme
   extensions = [
       # ...
       'openstackdocstheme',
       # ...
   ]
   
   html_theme = 'openstackdocs'
  • build初始文档

执行build出html和epub
make html
make epub