docs.cloud-atlas.io 文档的sphinx

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

2024年底，我重新开始 docs.cloud-atlas.io 项目，构建多语言、多版本Sphinx，我准备参考一些好的practice来完成，所以需要做一些测试

• Sphinx使用OpenStackDosTheme风格

• My Sphinx Best Practice Guide for Multi-version Documentation in Different Languages 支持多种语言和版本，经验分享

• How to manage translations for Sphinx projects 自动的多语言翻译(使用 Transifex 引擎实现)

初始化

• 安装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、Markdow格式和中文搜索，安装组件和配置
pip install sphinxcontrib-video
pip install sphinxcontrib-youtube
pip install myst-parser
pip install jieba

• 安装 openstackdocstheme 风格:

安装 openstackdocstheme 风格

pip install openstackdocstheme

• 初始化项目:

初始化sphinx文档

# 在项目目录下执行
sphinx-quickstart

备注

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

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

修订 conf.py 启用 openstackdocstheme

   extensions = [
       # ...
       'openstackdocstheme',
       # ...
   ]
   
   html_theme = 'openstackdocs'

• build初始文档

执行build出html和epub

make html
make epub