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 中国社区官方博客13 小时前
Elasticsearch 堆内存使用情况和 JVM 垃圾回收
大数据·jvm·数据库·elasticsearch·搜索引擎·全文检索
福尔摩东13 小时前
RAG全流程冠军思路! 实习or跳槽or项目实战
面试·github
DarrenPig13 小时前
【新能源科学与技术】MATALB/Simulink小白教程(一)实验文档【新能源电力转换与控制仿真】
matlab·开源·github·simulink·交流
码流怪侠15 小时前
arnis 在 GitHub 上短短三月暴增 7k star 🔥
github
Space-oddity-fang15 小时前
Ubuntu启动SMB(Samba)服务步骤
linux·服务器·github
2301_7664695615 小时前
本地项目上传到 GitHub流程
github
Gladiator57516 小时前
博客记录-day150-力扣(数位dp)
github
yangmf204019 小时前
私有知识库 Coco AI 实战(三):摄入 Elasticsearch 官方文档
人工智能·elasticsearch·搜索引擎·全文检索·coco ai
梓羽玩Python20 小时前
开源TTS领域迎来重磅新星!Dia-1.6B:超逼真对话生成,开源2天斩获6.5K Star!
人工智能·python·github
寻月隐君20 小时前
如何高效学习一门技术:从知到行的飞轮效应
后端·github