# Basic usage of Sphinx

## Project setup

```{note}
Wikiにページを追加したい場合は，[Edit source](#edit-source) から取り組んでください．
```

`sphinx-quickstart` コマンドを使用して新しいプロジェクトを作る  
いくつかの質問に答えていく．（デフォルト設定なら Enter，変更するなら内容を入力）
``` bash
$ sphinx-quickstart
Welcome to the Sphinx 7.2.6 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: test
> Author name(s): taro
> 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 /home/ryoukun/Documents/Python/test/source/conf.py.
Creating file /home/ryoukun/Documents/Python/test/source/index.rst.
Creating file /home/ryoukun/Documents/Python/test/Makefile.
Creating file /home/ryoukun/Documents/Python/test/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /home/ryoukun/Documents/Python/test/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.
```

<br>

以下のようなファイル構造でプロジェクトが作られる
```text
test
├── build
│    └── html
│         └── index.html  <-- ビルドすると生成される
├── source
│    ├── _static     <-- cssや画像データなどの静的ファイルを保存
│    ├── _templates  <-- テンプレートを保存
│    ├── conf.py     <-- 設定ファイル（テーマやファビコン，拡張子の設定）
│    └── index.rst   <-- ルートページとなるファイル
├── Makefile  <-- htmlに変換する際に使用する
└── make.bat
```


## Edit source
`source/` 内に reStructuredText or Markdown 形式のファイルを作成していく．  
`source/index.rst` を root として tree 構造となるように各ファイルを参照していく．  
（一般的なホームページと同じ）  
Markdown記法については，[Markdown](markdown.md)を参照



## Build
`make` コマンドを使用して，HTMLに変換する．  
Makefileがある位置でコマンドを実行する必要がある．
```bash
~/test/$ make html
```

`build/html/index.html` を開くと `index.rst` のデータがブラウザで見れる．

```{tip}
`sphinx build` コマンドでも可能．（make も内部でこれを実行している）  
ソースと生成先を指定できるため，ビルドコマンドが実行できる場所ならどこからでも
<pre>
<code class="bash">
# sphinx build -b html &ltoutput(build) folder&gt &ltsource folder&gt
sphinx build -b html build/ source/
</code>
</pre>
```