win11使用sphinx编写文档并部署到github page

Reference

1 安装

  1. 安装python3,这个自己找教程安装即可,记得配置环境变量

  2. 打开cmd,输入

    bash 复制代码
    pip install sphinx
  3. 创建一个文件夹zpdocs,在文件夹内打开cmd,初始化一个sphinx

    bash 复制代码
    sphinx-quickstart
    bash 复制代码
    > Separate source and build directories (y/n) [n]: y
    > Project name: zpdocs
    > Author name(s): zp
    > Project release []: 0.1
    > Project language [en]: zh_CN

    执行完毕后,就可以看见创建的工程文件:

    bash 复制代码
    |- build 
    |- source
    	|- _static 
    	|- _templates 
    	|- conf.py 
    	|- index.rst
    |- Makefile 
    |- make.bat 
    • build:文件夹,当你执行make html的时候,生成的html静态文件都存放在这里

    • source/_static:文件夹:图片,js等存放地址

    • source/_templates:文件夹:模板文件存放

    • source/index.rst:索引文件,文章目录大纲

    • source/conf.py:配置文件

    • make.bat:windows平台用于编译文档项目的makefile文件

    • Makefile:非windows平台用于编译文档项目的makefile文件

2 build项目

  1. 在文件夹zpdocs内打开cmd,运行

    bash 复制代码
    ./make html
  2. 打开zpdocs/build/html/index.html,编译成功

  3. 编译为http服务,这样可以通过ip地址查看网页

    1. 安装sphinx-autobuild

      bash 复制代码
      pip install sphinx-autobuild
    2. 重新编译

      bash 复制代码
      sphinx-autobuild source build/html

3 更改样式主题

  1. Sphnix官网查看自己想要样式

  2. 我使用Book主题,安装sphinx-book-theme

    bash 复制代码
    pip install sphinx-book-theme
  3. 修改source/conf.py文件中的html_theme字段

    python 复制代码
    html_theme = 'sphinx_book_theme'
  4. source/conf.py文件中的添加以下内容

    bash 复制代码
    source_suffix = {
        '.rst': 'restructuredtext',
        '.md': 'markdown'
    }
    
    html_title = "My amazing documentation"
    
    html_theme_options = {
        "show_navbar_depth": 1,
        "max_navbar_depth": 2,
        "collapse_navbar": True,
        "home_page_in_toc": True,
        "use_download_button": False,
    }
  5. 重新编译

    bash 复制代码
    sphinx-autobuild source build/html

4 支持markdown

  1. Sphinx默认只支持reST格式的文件。

    如果相要使用markdown格式的文档,还要安装markdown支持工具,命令如下:

    bash 复制代码
    pip install recommonmark
    pip install sphinx_markdown_tables
  2. 修改source/conf.pyextensions字段

    bash 复制代码
    extensions = ['recommonmark','sphinx_markdown_tables']
  3. 重新编译

    bash 复制代码
    sphinx-autobuild source build/html

5 编辑网页内容

  1. 修改source文件夹目录结构如下

    bash 复制代码
    |- build 
    |- source
    	|- _static 
    	|- _templates 
    	|- chapter1
    		|- section1
    			|- README.md
    		|- index.rst
    	|- chapter2
    		|- section1
    			|- README.md
    		|- index.rst
    	|- conf.py 
    	|- index.rst
    |- Makefile 
    |- make.bat 
    • source/index.rst

      bash 复制代码
      WELCOME!
      =============================
      .. toctree::  
         :maxdepth: 2  
         :caption: Contents  
      
         Chapter1<chapter1/index>  
         Chapter2<chapter2/index> 
    • source/chapter1/index.rst

      bash 复制代码
      Chapter 1
      =============================
      
      .. toctree::  
         :maxdepth: 2  
         :caption: Chapter 1  Contents
      
         S1.1<section1/README>  
    • source/chapter2/index.rst

      bash 复制代码
      Chapter 2
      =============================
      
      .. toctree::  
         :maxdepth: 2  
         :caption: Chapter 2  Contents
      
         S2.1<section1/README>  
    • source/chapter1/section1/README.md

      bash 复制代码
      # S1.1
    • source/chapter2/section1/README.md

      bash 复制代码
      # S2.1

6 部署到github page

  1. 在远程仓库创建一个仓库

  2. zpdocs文件夹打开cmd,输入./make clean清除build缓存

  3. 修改conf.py,添加

    bash 复制代码
    extensions = [...,'sphinx.ext.githubpages',...]

    这个插件会为生成后的文档添加 .nojekyll 文件, 也会为 GitHub Pages 自定义域名添加 CNAME 文件。 如果没有 .nojekyll, GitHub Pages 会认为 _ 开头的文件夹是 jekyll 内部文件夹, 然后将它过滤掉。

    注意: Sphinx 文档的文件名不能使用大写字母。 因为 Sphinx 在 windows 上输出时会把的文件名转成小写, 而

    GitHub Pages 的路由是大小写敏感的。 无法正确链接到使用了大写字母作为文件名的文件。

  4. 重新编译

    bash 复制代码
    sphinx-autobuild source build/html
  5. build/html的文件推送到仓库的main分支,仓库中setting->page设置如下:

相关推荐
Elastic 中国社区官方博客16 小时前
在 Elasticsearch 中改进 Agentic AI 工具的实验
大数据·数据库·人工智能·elasticsearch·搜索引擎·ai·全文检索
是垚不是土1 天前
Prometheus接入“飞书“实现自动化告警
运维·安全·自动化·github·飞书·prometheus
绝无仅有1 天前
消息队列mq面试经典问题与解答总结
后端·面试·github
绝无仅有1 天前
数据库mysql报错追踪与解决总结
后端·面试·github
啥都不会难搞2 天前
【傻呱呱】托管项目到GitHub(纯前端UI操作)
github
许商3 天前
【github】秘钥
github
草梅友仁3 天前
草梅 Auth 1.9.0 发布验证码组件 | 2025 年第 40 周草梅周报
开源·github·ai编程
Predestination王瀞潞4 天前
Github卡顿问题解决方案
github·解决方案
Elastic 中国社区官方博客4 天前
AutoOps:简单的 Elasticsearch 集群监控与管理现已支持本地部署
大数据·人工智能·elasticsearch·搜索引擎·云计算·全文检索
钟爱蛋炒饭4 天前
windows下使用github上传文件失败(编码问题)
github