# sphinx-doc

**Repository Path**: hl0929/sphinx-doc

## Basic Information

- **Project Name**: sphinx-doc
- **Description**: Sphinx 文档生成
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-07-03
- **Last Updated**: 2023-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# 初始化 Sphinx 工程

* 创建项目目录

```bash
mkdir sphinx-doc
cd sphinx-doc
```

* 初始化命令

```bash
sphinx-quickstart
```

* 命令输出结果

![](./asserts/sphinx-quickstart.jpg)

* 项目文件结构

```bash
│  make.bat
│  Makefile
├─build
└─source
    │  conf.py
    │  index.rst
    ├─_static
    └─_templates
```


# 编译项目

* 编译为本地文件

```bash
make html
```

build 目录下生成如下文件

```bash
│  make.bat
│  Makefile
├─build
│  ├─doctrees
│  │      environment.pickle
│  │      index.doctree
│  └─html
│      │  .buildinfo
│      │  genindex.html
│      │  index.html  # 这个文件可直接用浏览器打开
│      │  objects.inv
│      │  search.html
│      │  searchindex.js
│      │
│      ├─_sources
│      │      index.rst.txt
│      │
│      └─_static
│              alabaster.css
│              basic.css
│              custom.css
│              doctools.js
│              documentation_options.js
│              file.png
│              jquery-3.5.1.js
│              jquery.js
│              language_data.js
│              minus.png
│              plus.png
│              pygments.css
│              searchtools.js
│              translations.js
│              underscore-1.13.1.js
│              underscore.js
└─source
    │  conf.py
    │  index.rst
    ├─_static
    └─_templates
```

用浏览器打开 `build\html\index.rst` 可以看到
![](./asserts/preview.jpg)

* 编译为 HTTP 服务

`make html` 的编译方式需要打开 html 文件才能查看，使用如下命令则可以使用 HTTP 服务的形式来查看。

```bash
sphinx-autobuild source build/html
```

命令执行结果为
![](./asserts/http.jpg)

可以通过 http://127.0.0.1:8000/ 查看。


# Sphinx 主题

Sphinx 模型主题是 alabaster，可以通过 https://sphinx-themes.org/ 查看 sphinx 更多的主题。
![](./asserts/theme.jpg)

接下来切换一个比较明显的主题 `groundwork-sphinx-theme`，打开 `source/conf.py` 做如下修改
```bash
# html_theme = 'alabaster'
html_theme = 'groundwork'
```

# 增加 Sphinx 文档

* 新的项目文件结构如下
```bash
│  make.bat
│  Makefile
└─source
    │  conf.py
    │  index.rst
    ├─_static
    ├─_templates
    └─文章
        │  index.rst
        ├─第一章
        │      index.rst
        └─第二章
                index.rst

```

预览结果如下：
![](./asserts/homepage.jpg)