在Sphinx和GitHub Pages上发布您的技术说明！

介绍

当您进行一些技术研究时(当然，它不必一定是技术性的)，您经常以某种形式输出它。例如Qiita，Hatena Blog，Wiki。

这次，我将介绍您可以使用Sphinx + GitHub Pages在Web上相对轻松地创建和输出技术说明。不仅可以生成网页，而且可以生成PDF。

假定的环境是Windows 10。我还没有尝试过，但是我认为在MacOS上还可以。

它可以用于各种目的，从浅色网页到纯文档。例如，Docker文档日语本地化项目使用Sphinx。

什么是狮身人面像？

Sphinx是一种可以轻松创建智能且美观的文档的工具。由Georg Brandl开发的Python制作的工具。

安装方法

因此，我将立即安装Python。在此处下载并安装Python3。

1 2	D:\>python --version Python 3.7.3

然后使用pip install安装Sphinx。基本上遵循Sphinx第一步的用户文档。

1	D:\>pip install sphinx

如何使用

项目创建

首先，让我们创建一个项目。您可以使用sphinx-quickstart命令创建一个项目。系统将以某种方式询问您，但是基本上您可以按Enter。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

D:\note>sphinx-quickstart
Welcome to the Sphinx 2.1.2 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

The project name will occur in several places in the built documentation.
> Project name: sample-project
> Author name(s): tsuji
> Project release []:

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: ja

Creating file .\source\conf.py.
Creating file .\source\index.rst.
Creating file .\Makefile.
Creating file .\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file .\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

项目创建完成后，可以看到具有以下配置的文件已生成。

1
2
3
4
5
6
7
8
9
10
11
12

D:\note>tree /f
D:.
│ make.bat
│ Makefile
│
├─build
└─source
│ conf.py
│ index.rst
│
├─_static
└─_templates

您可以使用

make.bat生成HTML文件或在本地预览。

文档创建

现在，我们创建文档。首先，创建一个索引文档，该索引文档将用作网站首页和注释的目录。 (尽管文件是自动生成的)

点是使用称为reStructuredText的标记语言编写的。我认为有很多人会说降价！我也一样刚开始您可能不熟悉如何编写reStructuredText，但是reStructuredText是一种简单，简单的标记语言，您很快就会习惯。似乎reStructuredText通常缩写为reST，因此我们将其缩写为reST。

成为

索引的文件是index.rst。如果您向里看，您会发现它看起来像下面的样子。

索引

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

.. sample-project documentation master file, created by
sphinx-quickstart on Mon Jul 8 22:38:47 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

Welcome to sample-project's documentation!
==========================================

.. toctree::
:maxdepth: 2
:caption: Contents:

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

让我们立即构建它并生成一个HTML文件。可以使用make.bat使用make html命令完成构建。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

D:\note>make html
Running Sphinx v2.1.2
loading translations [ja]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in Japanese (code: ja) ... done
dumping object inventory... done
build succeeded.

The HTML pages are in build\html.

您可以看到在

build\html下生成了一个名为index.html的文件。访问它时，您可以看到它如下。

添加内容

如果可以创建索引页面，则要添加内容，对吗？我将其添加。如下所示添加到index.rst并创建一个名为hello.rst的文件。添加一个名为" First Sphinx"的页面。

索引

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

.. sample-project documentation master file, created by
sphinx-quickstart on Mon Jul 8 22:38:47 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

Welcome to sample-project's documentation!
==========================================

.. toctree::
:maxdepth: 2
:caption: Contents:

+ hello

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

你好

1
2
3
4

+はじめてのSphinx
+===============================
+
+Hello Sphinx!!!

如果使用

make html构建并再次访问index.html，将看到以下内容。

您可以看到已经添加了" First Sphinx"页面。让我们访问此页面。

页面内容正确显示。

层次内容

您可以使用

层次结构轻松添加内容。让我们在index.rst中添加一个带有段落的页面。添加到index.rst并创建一个新文件hierarchy.rst。

索引

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

.. sample-project documentation master file, created by
sphinx-quickstart on Mon Jul 8 22:38:47 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

Welcome to sample-project's documentation!
==========================================

.. toctree::
:maxdepth: 2
:caption: Contents:

hello
+ hierarchy

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

层次结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

+段落
+==================================
+
+---------------------------------
+段落1
+---------------------------------
+
+AAAAAA
+
+---------------------------------
+段落2
+---------------------------------
+
+BBBBBB
+
+---------------------------------
+段落3
+---------------------------------
+
+CCCCCC
+
+---------------------------------
+段落4
+---------------------------------
+
+DDDDDD

hierarchy.rst用reST编写。您可能需要时可以在这里看看。

使用

make html构建和访问。然后您可以看到已添加具有层次结构的页面。

代码说明

当然，您可以编写

代码并通过语法突出显示来显示。

索引

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

.. sample-project documentation master file, created by
sphinx-quickstart on Mon Jul 8 22:38:47 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

Welcome to sample-project's documentation!
==========================================

.. toctree::
:maxdepth: 2
:caption: Contents:

hello
hierarchy
+ code

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

可以使用.. code-block::编写

代码。

源/ code.rst

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

+コードを記述
+==================================
+
+`` .. code-block:: `` を用いることでコードをハイライトすることができます。
+
+.. code-block:: go
+ :caption: hello.go
+
+ package main
+
+ import "fmt"
+
+ func main() {
+ fmt.Println("Hello, world!")
+ }

它将显示如下。

点是您需要正确的缩进和空白行。不只是(.. code-block::)。除非您包含缩进和空白行，否则它将不会显示。

例如，如果您执行以下操作，则不会显示它。您需要小心，因为很难注意到。我首先沉迷于此。

源/ code.rst

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

コードを記述
==================================

`` .. code-block:: `` を用いることでコードをハイライトすることができます。

.. code-block:: go
コードを記述
==================================
+
+表示されるコード
+-------------------------------------------------

``` .. code-block:: ``` を用いることでコードをハイライトすることができます。

.. code-block:: go
:caption: hello.go

package main

import "fmt"

func main() {
fmt.Println("Hello, world!")
}
+
+正しく表示されないコード(その1：インデントがない)
+--------------------------------------------------
+
+.. code-block:: go
+
+package main
+
+import "fmt"
+
+func main() {
+ fmt.Println("Hello, world!")
+}
+
+正しく表示されないコード(その2：空行がない)
+-------------------------------------------------
+
+.. code-block:: go
+ package main
+
+ import "fmt"
+
+ func main() {
+ fmt.Println("Hello, world!")
+ }

看起来像这样。

其他各种描述方法

除了

层次结构以外，还可以使用reST进行各种描述。我将介绍以下描述方法，它是其中的一部分。

表
脚注
式
去做

索引

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

.. sample-project documentation master file, created by
sphinx-quickstart on Mon Jul 8 22:38:47 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

Welcome to sample-project's documentation!
==========================================

.. toctree::
:maxdepth: 2
:caption: Contents:

hello
hierarchy
code
+ other

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

+.. todolist::

来源/other.rst

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

+その他の機能
+==================================
+
+---------------------------------
+テーブル
+---------------------------------
+
+===== ===== =======
+A B A and B
+===== ===== =======
+False False False
+True False False
+False True False
+True True True
+===== ===== =======
+
+---------------------------------
+脚注
+---------------------------------
+
+これは脚注 [#]_ です。
+
+.. [#] 本文の下の方につける注記
+
+---------------------------------
+数式
+---------------------------------
+
+数式を有効にするには、``conf.py`` に ``sphinx.ext.mathjax`` という拡張モジュールを追加する必要があります。以下のような感じです。モジュールを有効にすれば、LaTeX で数式を記述することができます。
+
+.. code-block:: python
+ :caption: conf.py
+
+ # Add any Sphinx extension module names here, as strings. They can be
+ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+ # ones.
+ extensions = ['sphinx.ext.mathjax'
+ ]
+
+`N` 個の整数 :math:`d[0], d[1], \dots, d[N-1]` が与えられます。これは数式のサンプルです。
+
+---------------------------------
+TODO
+---------------------------------
+
+TODOも拡張モジュール ``sphinx.ext.todo`` を有効にすると記述できるようになります。あとでやりたいことを残しておくときに便利ですね。
+
+.. code-block:: none
+ :caption: conf.py
+
+ # Add any Sphinx extension module names here, as strings. They can be
+ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+ # ones.
+ extensions = ['sphinx.ext.mathjax', 'sphinx.ext.todo'
+ ]
+
+ [extensions]
+ todo_include_todos = True
+
+.. todo::
+
+ これは TODO なので、後ほど調査する
+
+TODOを表示する場所も選ぶことができます。今回は index ページに記載しておきましょう。表示させたい場所に ``` .. todolist:: ``` と記述しておけばよいです。
+
+.. code-block:: rest
+
+ .. sample-project documentation master file, created by
+ sphinx-quickstart on Mon Jul 8 22:38:47 2019.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+ Welcome to sample-project's documentation!
+ ==========================================
+
+ .. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+ hello
+ hierarchy
+ code
+ other
+
+ Indices and tables
+ ==================
+
+ * :ref:`genindex`
+ * :ref:`modindex`
+ * :ref:`search`

看起来像这样。真漂亮。

预览

到目前为止，它是页面的描述方法。现在，我将向您展示一种便捷的构建方法。

到现在为止，每次修改文件时，我都使用make html生成文件以生成HTML并进行检查。如果您多次更改它会有点烦人。如果文件更改自动反映在网页中，那就太好了。

如果使用

Sphinx sphinx-autobuild，对该文件的任何更改将自动运行该版本以反映更新。方便。让我们使用它。

sphinx-autobuild模块是必需的，因此请使用pip进行安装。

1	pip install sphinx-autobuild

安装

后，用sphinx-autobuild命令启动它。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

$ sphinx-autobuild -b html source build/html

+--------- manually triggered build ---------------------------------------------
| Running Sphinx v2.1.2
| loading translations [ja]... done
| building [mo]: targets for 0 po files that are out of date
| building [html]: targets for 5 source files that are out of date
| updating environment: 5 added, 0 changed, 0 removed
| reading sources... [ 20%] code
| reading sources... [ 40%] hello
| reading sources... [ 60%] hierarchy
| reading sources... [ 80%] index
| reading sources... [100%] other
|
| looking for now-outdated files... none found
| pickling environment... done
| checking consistency... done
| preparing documents... done
| writing output... [ 20%] code
| writing output... [ 40%] hello
| writing output... [ 60%] hierarchy
| writing output... [ 80%] index
| writing output... [100%] other
|
| generating indices... genindex
| writing additional pages... search
| copying static files... done
| copying extra files... done
| dumping search index in Japanese (code: ja) ... done
| dumping object inventory... done
| build succeeded.
|
| The HTML pages are in build\html.
+--------------------------------------------------------------------------------

[I 190709 08:34:05 server:296] Serving on http://127.0.0.1:8000
[I 190709 08:34:05 handlers:62] Start watching changes
[I 190709 08:34:05 handlers:64] Start detecting changes

您可以看到

导致Web服务器在端口8000上进行本地侦听。如果从浏览器访问以下内容，则可以看到显示了本地构建的内容和生成的HTML。

1	http://localhost:8000/

如果您发现记住

sphinx-autobuild的命令有些麻烦，可以将它们添加到make.bat可能很方便。
如下所示将其添加到make.bat。

make.bat

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

@ECHO OFF

pushd %~dp0

REM Command file for Sphinx documentation

if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build

if "%1" == "" goto help

if "%1" == "preview" (
echo.Running sphinx-autobuild. View live edits at:
echo. http://0.0.0.0:8000
sphinx-autobuild -b html %SOURCEDIR% %BUILDDIR%/html
if errorlevel 1 exit /b 1
goto end
)

%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)

+:html
+%SPHINXBUILD% -b html %SOURCEDIR% "docs" %SPHINXOPTS% %O%
+goto end

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
popd

启动时，

如下

1	make preview

您可以使用

。

与GitHub Pages

合作

现在我们已经在本地创建了文档，让我们将其发布在GitHub Pages上。能够在GitHub上管理文档的源代码时轻松发布会很好。

首先，将创建的文档上传到GitHub。 GitHub的存储库名称应为sphinx-sample。

.gitignore

1 2	+build/doctrees +.DS_Store

1
2
3
4
5

git init
git add -A
git commit -m "init"
git remote add origin https://github.com/d-tsuji/sphinx-sample.git
git push -u origin master

在GitHub Pages上发布时，这次我将使用master分支的docs目录发布。
因此，在构建时修改目录输出。构建时的命令为make html。

make.bat

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

如果使用

make html进行构建，则可以看到在docs目录中生成了HTML文件。 build目录是不必要的，因此将其删除。

目录结构如下。 (省略了HTML文件和doctree文件)

1
2
3
4
5
6
7
8
9

D:.
│ .gitignore
│ make.bat
│ Makefile
├─docs
│ ├─.doctrees
│ ├─_sources
│ └─_static
└─source

提交并上传到GitHub。

从GitHub GUI设置GitHub Pages。如下。

设置

后，访问URL(https://d-tsuji.github.io/sphinx-sample/)。

然后您可以看到CSS不够出色。很可悲，不是吗。

默认情况下，GitHi Pages托管在JekyII上。但是，JekyII不支持Sphinx，因此它无法读取诸如_static之类的路径。作为响应，您需要创建一个.nojekyll目录。如果手动创建它没有问题，但是这次您可以使用sphinx.ext.githubpages来处理它。

sphinx.ext.githubpages插件在您的HTML目录中创建一个.nojekyll文件，以便在GitHub Pages上发布。

来源/ conf.py

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

...

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ['sphinx.ext.mathjax', 'sphinx.ext.todo'
+extensions = ['sphinx.ext.mathjax', 'sphinx.ext.todo', 'sphinx.ext.githubpages'
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

...

用

conf.py激活插件后，用make html重新构建。然后您可以看到docs/.nojekyll目录已创建。

在这种状态下推送到GitHub。

尝试再次访问https://d-tsuji.github.io/sphinx-sample/。

您可以看到CSS可以正常工作，感觉很好！ !! !!

可以从conf.py设置

页面设计。 (如果要选择Sphinx不包含的主题，则需要进行其他设置，例如theme.conf。)默认情况下，它是alabaster，如下所示。

来源/ conf.py

1
2
3
4
5
6
7
8
9
10

...

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

...

下面是每个主题的示例。

https://sphinx-themes.org/

最初介绍的Docker文档日语本地化项目的主题是sphinx_rtd_theme。您可以根据自己的口味选择。

摘要

我能够使用Sphinx创建像技术说明一样的静态网页，并将其发布在GitHub Pages上。

尽管这次没有介绍，但是您可以从同一源文件创建PDF文件以及HTML文件。这是一个易于使用的简单工具，您可能需要编写大量文档。

参考

http://www.sphinx-doc.org/en/master/

https://docs.sphinx-users.jp/index.html#