sphinx¶
sphinx는 document generation을 위한 라이브러이임
document 작성을 위한 언어로 rst를 기본으로 하며(markdown도 지원)
python docstring을 자동화하여 api document생성 지원.
(공식 python document도 sphinx를 이용하여 제공하고 있음)
environment 준비¶
import os
home_dir = os.path.expanduser('~')
# work_dir = f'{home_dir}/sphinx_demo'
print(home_dir)
/home/runner
!pip install pdm
Requirement already satisfied: pdm in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (2.7.4)
Requirement already satisfied: blinker in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (1.6.2)
Requirement already satisfied: certifi in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (2023.5.7)
Requirement already satisfied: packaging!=22.0,>=20.9 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (23.1)
Requirement already satisfied: platformdirs in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (3.8.0)
Requirement already satisfied: rich>=12.3.0 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (13.4.2)
Requirement already satisfied: virtualenv>=20 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (20.23.1)
Requirement already satisfied: pyproject-hooks in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (1.0.0)
Requirement already satisfied: requests-toolbelt in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (1.0.0)
Requirement already satisfied: unearth>=0.9.0 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (0.9.2)
Requirement already satisfied: findpython>=0.2.2 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (0.2.5)
Requirement already satisfied: tomlkit<1,>=0.11.1 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (0.11.8)
Requirement already satisfied: shellingham>=1.3.2 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (1.5.0.post1)
Requirement already satisfied: python-dotenv>=0.15 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (1.0.0)
Requirement already satisfied: resolvelib>=1.0.1 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (1.0.1)
Requirement already satisfied: installer<0.8,>=0.7 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (0.7.0)
Requirement already satisfied: cachecontrol[filecache]>=0.13.0 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (0.13.1)
Requirement already satisfied: tomli>=1.1.0 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from pdm) (2.0.1)
Requirement already satisfied: requests>=2.16.0 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from cachecontrol[filecache]>=0.13.0->pdm) (2.31.0)
Requirement already satisfied: msgpack>=0.5.2 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from cachecontrol[filecache]>=0.13.0->pdm) (1.0.5)
Requirement already satisfied: filelock>=3.8.0 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from cachecontrol[filecache]>=0.13.0->pdm) (3.12.2)
Requirement already satisfied: markdown-it-py>=2.2.0 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from rich>=12.3.0->pdm) (3.0.0)
Requirement already satisfied: pygments<3.0.0,>=2.13.0 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from rich>=12.3.0->pdm) (2.15.1)
Requirement already satisfied: distlib<1,>=0.3.6 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from virtualenv>=20->pdm) (0.3.6)
Requirement already satisfied: mdurl~=0.1 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from markdown-it-py>=2.2.0->rich>=12.3.0->pdm) (0.1.2)
Requirement already satisfied: charset-normalizer<4,>=2 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from requests>=2.16.0->cachecontrol[filecache]>=0.13.0->pdm) (3.1.0)
Requirement already satisfied: idna<4,>=2.5 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from requests>=2.16.0->cachecontrol[filecache]>=0.13.0->pdm) (3.4)
Requirement already satisfied: urllib3<3,>=1.21.1 in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages (from requests>=2.16.0->cachecontrol[filecache]>=0.13.0->pdm) (2.0.3)
[notice] A new release of pip is available: 23.0.1 -> 23.1.2
[notice] To update, run: pip install --upgrade pip
work_dir = f'{home_dir}/sphinx_demo'
print(work_dir)
/home/runner/sphinx_demo
if not os.path.isdir(work_dir):
os.mkdir(work_dir)
# else:
# os.system(f'rm -rf '+work_dir)
# os.mkdir(work_dir)
os.chdir(work_dir)
!pwd
/home/runner/sphinx_demo
install¶
!pdm init -n
Creating a pyproject.toml for PDM...
Virtualenv is created successfully at /home/runner/sphinx_demo/.venv
Changes are written to pyproject.toml.
!pdm venv create -w virtualenv
?25l
⠋ Creating virtualenv using virtualenv...
?25h
[VirtualenvCreateError]: The location /home/runner/sphinx_demo/.venv is not
empty, add --force to overwrite it.
!pdm use --venv in-project
Using Python interpreter: /home/runner/sphinx_demo/.venv/bin/python (3.10)
!pdm add sphinx
Show code cell output
Adding group default to lockfile
Adding packages to default dependencies: sphinx
?25l
⠋ Resolving dependencies
⠙ Resolving dependencies
⠹ Resolving dependencies
⠸ Resolving dependencies
⠼ Resolving: new pin python>=3.10
⠴ Resolving: new pin python>=3.10
⠦ Resolving: new pin python>=3.10
⠧ Resolving: new pin python>=3.10
⠇ Resolving: new pin python>=3.10
⠏ Resolving: new pin python>=3.10
⠋ Resolving: new pin python>=3.10
⠙ Resolving: new pin python>=3.10
⠹ Resolving: new pin python>=3.10
⠸ Resolving: new pin python>=3.10
⠼ Resolving: new pin python>=3.10
⠴ Resolving: new pin python>=3.10
⠦ Resolving: new pin python>=3.10
⠧ Resolving: new pin python>=3.10
⠇ Resolving: new pin python>=3.10
⠏ Resolving: new pin python>=3.10
⠋ Resolving: new pin python>=3.10
⠙ Resolving: new pin python>=3.10
⠹ Resolving: new pin python>=3.10
⠸ Resolving: new pin python>=3.10
⠼ Resolving: new pin sphinx 7.0.1
⠴ Resolving: new pin sphinx 7.0.1
⠦ Resolving: new pin sphinx 7.0.1
⠧ Resolving: new pin sphinx 7.0.1
⠇ Resolving: new pin sphinx 7.0.1
⠏ Resolving: new pin sphinx 7.0.1
⠋ Resolving: new pin sphinx 7.0.1
⠙ Resolving: new pin imagesize 1.4.1
⠹ Resolving: new pin imagesize 1.4.1
⠸ Resolving: new pin Jinja2 3.1.2
⠼ Resolving: new pin Pygments 2.15.1
⠴ Resolving: new pin Pygments 2.15.1
⠦ Resolving: new pin Pygments 2.15.1
⠧ Resolving: new pin Pygments 2.15.1
⠇ Resolving: new pin Pygments 2.15.1
⠏ Resolving: new pin Pygments 2.15.1
⠋ Resolving: new pin requests 2.31.0
⠙ Resolving: new pin requests 2.31.0
⠹ Resolving: new pin sphinxcontrib-jsmath 1.0.1
⠼ Fetching hashes for resolved packages...
⠴ Fetching hashes for resolved packages...
⠦ Fetching hashes for resolved packages...
⠧ Fetching hashes for resolved packages...
⠇ Fetching hashes for resolved packages...
⠏ Fetching hashes for resolved packages...
⠋ Fetching hashes for resolved packages...
⠙ Fetching hashes for resolved packages...
?25h
🔒 Lock successful
Changes are written to pyproject.toml.
?25l
⠋ Resolving packages from lockfile...
⠋ Fetching hashes for resolved packages...
?25h
Synchronizing working set with lock file: 21 to add, 0 to update, 0 to remove
?25l
⠋ Installing alabaster 0.7.13...
⠋ Installing alabaster 0.7.13...
⠋ Installing babel 2.12.1...
✔ Install alabaster 0.7.13 successful
⠋ Installing alabaster 0.7.13...
⠋ Installing babel 2.12.1...
⠋ Installing babel 2.12.1...
⠋ Installing certifi 2023.5.7...
✔ Install certifi 2023.5.7 successful
⠋ Installing babel 2.12.1...
⠋ Installing certifi 2023.5.7...
⠙ Installing babel 2.12.1...
⠙ Installing charset-normalizer 3.1.0...
⠙ Installing babel 2.12.1...
⠙ Installing charset-normalizer 3.1.0...
✔ Install charset-normalizer 3.1.0 successful
⠙ Installing babel 2.12.1...
⠙ Installing charset-normalizer 3.1.0...
⠹ Installing babel 2.12.1...
⠹ Installing docutils 0.20.1...
⠹ Installing babel 2.12.1...
⠹ Installing docutils 0.20.1...
⠸ Installing babel 2.12.1...
⠸ Installing docutils 0.20.1...
⠴ Installing babel 2.12.1...
⠴ Installing docutils 0.20.1...
✔ Install docutils 0.20.1 successful
⠴ Installing babel 2.12.1...
⠴ Installing docutils 0.20.1...
⠦ Installing babel 2.12.1...
⠦ Installing idna 3.4...
⠦ Installing babel 2.12.1...
⠦ Installing idna 3.4...
✔ Install idna 3.4 successful
⠦ Installing babel 2.12.1...
⠦ Installing idna 3.4...
⠦ Installing babel 2.12.1...
⠦ Installing imagesize 1.4.1...
✔ Install imagesize 1.4.1 successful
⠦ Installing babel 2.12.1...
⠦ Installing imagesize 1.4.1...
⠧ Installing babel 2.12.1...
⠧ Installing jinja2 3.1.2...
⠧ Installing babel 2.12.1...
⠧ Installing jinja2 3.1.2...
✔ Install jinja2 3.1.2 successful
⠧ Installing babel 2.12.1...
⠧ Installing jinja2 3.1.2...
⠇ Installing babel 2.12.1...
⠇ Installing markupsafe 2.1.3...
✔ Install markupsafe 2.1.3 successful
⠇ Installing babel 2.12.1...
⠇ Installing markupsafe 2.1.3...
⠇ Installing babel 2.12.1...
⠇ Installing packaging 23.1...
⠏ Installing babel 2.12.1...
⠏ Installing packaging 23.1...
✔ Install packaging 23.1 successful
⠏ Installing babel 2.12.1...
⠏ Installing packaging 23.1...
⠏ Installing babel 2.12.1...
⠏ Installing pygments 2.15.1...
⠋ Installing babel 2.12.1...
⠋ Installing pygments 2.15.1...
⠙ Installing babel 2.12.1...
⠙ Installing pygments 2.15.1...
✔ Install pygments 2.15.1 successful
⠙ Installing babel 2.12.1...
⠙ Installing pygments 2.15.1...
⠹ Installing babel 2.12.1...
⠹ Installing requests 2.31.0...
⠸ Installing babel 2.12.1...
⠸ Installing requests 2.31.0...
✔ Install requests 2.31.0 successful
⠸ Installing babel 2.12.1...
⠸ Installing requests 2.31.0...
⠸ Installing babel 2.12.1...
⠸ Installing snowballstemmer 2.2.0...
✔ Install babel 2.12.1 successful
⠸ Installing babel 2.12.1...
⠸ Installing snowballstemmer 2.2.0...
⠸ Installing snowballstemmer 2.2.0...
⠸ Installing sphinx 7.0.1...
✔ Install snowballstemmer 2.2.0 successful
⠸ Installing snowballstemmer 2.2.0...
⠸ Installing sphinx 7.0.1...
⠼ Installing sphinx 7.0.1...
⠼ Installing sphinxcontrib-applehelp 1.0.4...
⠼ Installing sphinx 7.0.1...
⠼ Installing sphinxcontrib-applehelp 1.0.4...
✔ Install sphinxcontrib-applehelp 1.0.4 successful
⠼ Installing sphinx 7.0.1...
⠼ Installing sphinxcontrib-applehelp 1.0.4...
⠼ Installing sphinx 7.0.1...
⠼ Installing sphinxcontrib-devhelp 1.0.2...
✔ Install sphinxcontrib-devhelp 1.0.2 successful
⠼ Installing sphinx 7.0.1...
⠼ Installing sphinxcontrib-devhelp 1.0.2...
⠴ Installing sphinx 7.0.1...
⠴ Installing sphinxcontrib-htmlhelp 2.0.1...
⠴ Installing sphinx 7.0.1...
⠴ Installing sphinxcontrib-htmlhelp 2.0.1...
✔ Install sphinxcontrib-htmlhelp 2.0.1 successful
⠴ Installing sphinx 7.0.1...
⠴ Installing sphinxcontrib-htmlhelp 2.0.1...
⠦ Installing sphinx 7.0.1...
⠦ Installing sphinxcontrib-jsmath 1.0.1...
⠧ Installing sphinx 7.0.1...
⠧ Installing sphinxcontrib-jsmath 1.0.1...
✔ Install sphinxcontrib-jsmath 1.0.1 successful
⠧ Installing sphinx 7.0.1...
⠧ Installing sphinxcontrib-jsmath 1.0.1...
⠧ Installing sphinx 7.0.1...
⠧ Installing sphinxcontrib-qthelp 1.0.3...
✔ Install sphinxcontrib-qthelp 1.0.3 successful
⠧ Installing sphinx 7.0.1...
⠧ Installing sphinxcontrib-qthelp 1.0.3...
⠇ Installing sphinx 7.0.1...
⠇ Installing sphinxcontrib-serializinghtml 1.1.5...
⠇ Installing sphinx 7.0.1...
⠇ Installing sphinxcontrib-serializinghtml 1.1.5...
✔ Install sphinxcontrib-serializinghtml 1.1.5 successful
⠇ Installing sphinx 7.0.1...
⠇ Installing sphinxcontrib-serializinghtml 1.1.5...
⠏ Installing sphinx 7.0.1...
⠏ Installing urllib3 2.0.3...
⠏ Installing sphinx 7.0.1...
⠏ Installing urllib3 2.0.3...
✔ Install urllib3 2.0.3 successful
⠏ Installing sphinx 7.0.1...
⠏ Installing urllib3 2.0.3...
⠋ Installing sphinx 7.0.1...
✔ Install sphinx 7.0.1 successful
⠋ Installing sphinx 7.0.1...
🎉 All complete!
⠋ Installing sphinx 7.0.1...
?25h
!pdm list --graph
sphinx 7.0.1 [ required: >=7.0.1 ]
├── alabaster 0.7.13 [ required: <0.8,>=0.7 ]
├── babel 2.12.1 [ required: >=2.9 ]
├── docutils 0.20.1 [ required: <0.21,>=0.18.1 ]
├── imagesize 1.4.1 [ required: >=1.3 ]
├── jinja2 3.1.2 [ required: >=3.0 ]
│ └── markupsafe 2.1.3 [ required: >=2.0 ]
├── packaging 23.1 [ required: >=21.0 ]
├── pygments 2.15.1 [ required: >=2.13 ]
├── requests 2.31.0 [ required: >=2.25.0 ]
│ ├── certifi 2023.5.7 [ required: >=2017.4.17 ]
│ ├── charset-normalizer 3.1.0 [ required: <4,>=2 ]
│ ├── idna 3.4 [ required: <4,>=2.5 ]
│ └── urllib3 2.0.3 [ required: <3,>=1.21.1 ]
├── snowballstemmer 2.2.0 [ required: >=2.0 ]
├── sphinxcontrib-applehelp 1.0.4 [ required: Any ]
├── sphinxcontrib-devhelp 1.0.2 [ required: Any ]
├── sphinxcontrib-htmlhelp 2.0.1 [ required: >=2.0.0 ]
├── sphinxcontrib-jsmath 1.0.1 [ required: Any ]
├── sphinxcontrib-qthelp 1.0.3 [ required: Any ]
└── sphinxcontrib-serializinghtml 1.1.5 [ required: >=1.1.5 ]
create book¶
!pdm run sphinx-quickstart docs -q -p sph_test -a YB
Finished: An initial directory structure has been created.
You should now populate your master file /home/runner/sphinx_demo/docs/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.
!tree .
.
├── docs
│ ├── Makefile
│ ├── _build
│ ├── _static
│ ├── _templates
│ ├── conf.py
│ ├── index.rst
│ └── make.bat
├── pdm.lock
└── pyproject.toml
4 directories, 6 files
build¶
!pdm run sphinx-build docs/ docs/_build/html
Running Sphinx v7.0.1
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 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
done
writing additional pages... search done
copying static files...
done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.
The HTML pages are in docs/_build/html.