PyCon JP TV #25 sample project

takanory

Jan 20, 2023

Contents:1

SphinxãĄĺãĄŕ
1.1 SphinxãĆŠä¡£ãĄčãĄęãĄĎãĆŃãĆțãĆďãČĹãĄőçťźäżŃ . . . . . . . . . . . . . . . . . . . . . . . . .

1
12Quickstart
2.1 githubãĄğãČłãČİãĆÿãČĹãČłä¡ĲæĹŘ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 SphinxãĆďãČşãĆźãČĹãČĳãČń . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Sphinx quick start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4 ãČȚãĆąãĆďãČńæğŃæĹŘãĆŠçćžèłŊ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5 rstãĆŠæŻÿãĄŊæŔŻãĄĹãĆŃ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3333443ãĆńãĆźãĆ£ãČđãĆďãĆž
3.1 ãČĘãČĳãČđåďĽæŻť . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 ãČŋãĆťçŤżåČŔãĆŠè£¡åŁă . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5554

markdownåŕ¿å£Ĳ
4.1 myst-parserãĆŠè£¡åŁă . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 markdownãĄőãČȚãĆąãĆďãČńãĆŠè£¡åŁă . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7775

ãČĘãČĳãČđãĆŠåďĽãĄĹãĆŃ
5.1 Read the Docs Sphinx Theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 Furo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9996

Read the Docs ãĄğãČĞãČŮãČŋãĆďãĄŹãĆŃ
6.1 requirements.txtãĆŠè£¡åŁă . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 Read the DocsãĄőãĆćãĆńãĆęãČşãČĹèĺŋåőŽ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3 ãČĽãĆŋãČěãČąãČşãČĹãĆŠä£őæŋčãĄŮãĄęPush . . . . . . . . . . . . . . . . . . . . . . . . . . . .

111111127ãĄŁãĄŹãĄŹãĆĄæŃąåĳțæľ§èČ¡
7.1 sphinxext-opengraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2 sphinx-copybutton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3 sphinx-design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4 sphinx-pyscript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

13131414158ãČĘãĆźãČĹãČĽãĆŋãČěãČąãČşãČĹ
8.1 Font Awesome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2 PyScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

17
1919

9Indices and tables

21i

ii

Chapter 1SphinxãĄĺãĄŕ
• SphinxãĄőçťźäżŃ: https://www.sphinx-doc.org/ja/master/• Pythonèč¡ãĄőãČĽãĆŋãČěãČąãČşãČĹçŤ§æĹŘãČĎãČĳãČń
• HTMLãĆĎepubãĂĄPDFãĄłãĄľãĄńåĞžåŁŻãĄğãĄŊãĆŃ• éİŹçŽĎãĆțãĆďãČĹãĆÿãĆğãČŊãČňãČĳãĆ£ãČĳ

1.1 SphinxãĆŠä¡£ãĄčãĄęãĄĎãĆŃãĆțãĆďãČĹãĄőçťźäżŃ
• SphinxãĆŠä¡£çŤĺãĄŮãĄęãĄĎãĆŃãČŮãČŋãĆÿãĆğãĆŕãČĹ âĂŤ Sphinx documentation• PythonåĚňåĳŔãČĽãĆŋãČěãČąãČşãČĹ
• Flake8ãČĽãĆŋãČěãČąãČşãČĹ
• PEP 0 – Index of Python Enhancement Proposals (PEPs) | peps.python.org

1

PyCon JP TV #25 sample project2

Chapter 1. SphinxãĄĺãĄŕ

Chapter 2Quickstart
2.1 githubãĄğãČłãČİãĆÿãČĹãČłä¡ĲæĹŘ• githubãĄğãČłãČİãĆÿãČĹãČłãĆŠä¡ĲæĹŘãĄŹãĆŃ https://github.com/takanory/$ git clone git@github.com:takanory/pyconjptv25-sphinx-sample.git$ cd pyconjptv25-sphinx-sample

2.2 SphinxãĆďãČşãĆźãČĹãČĳãČń
• èńÿèĹňãĄőäžŃæČĚãĄğæĲĂæŰřãĄğãĄŕãĄłãĄŔSphinx 5.3.0ãĆŠãĆďãČşãĆźãČĹãČĳãČńãĄŹãĆŃ
$ python3.10 -m venv env$ . env/bin/activate(env) $ pip install sphinx==5.3.0

2.3 Sphinx quick start• sphinxãĄğHTMLãĆŠçŤ§æĹŘãĄŮãĄęèąĺçďž
(env) $ sphinx-quickstart> Separate source and build directories (y/n) [n]: y> Project name: PyCon JP TV #25 sample project> Author name(s): takanory> Project release []:> Project language [en]: ja(env) $ make html(env) $ ls build/html(env) $ open build/html/index.html

3

PyCon JP TV #25 sample project

2.4 ãČȚãĆąãĆďãČńæğŃæĹŘãĆŠçćžèłŊ
• ãČȚãĆąãĆďãČńæğŃæĹŘãĆŠçćžèłŊãĄŹãĆŃ(env) $ ls -CF
LICENSE
Makefile# ãČȚãĆąãĆďãČńãĆŠçćžèłŊREADME.mdenv
build
make.batsource2.5 rstãĆŠæŻÿãĄŊæŔŻãĄĹãĆŃ
• source/index.rst ãĆŠæŻÿãĄŊæŔŻãĄĹãĆŃ
• reStructuredTextåĚěéŰĂ âĂŤ Sphinx documentation(env) $ make html

4

Chapter 2. QuickstartChapter 3ãĆńãĆźãĆ£ãČđãĆďãĆž
3.1 ãČĘãČĳãČđåďĽæŻť
• HTML Theming âĂŤ Sphinx documentation• ãČĘãČĳãČđãĆŠ bizstyle ãĄńåďĽæŻť(env) $ vi source/conf.py(env) $ make html

3.2 ãČŋãĆťçŤżåČŔãĆŠè£¡åŁă• https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output• çŤżåČŔãČȚãĆąãĆďãČń: https://tv.pycon.jp/_images/eyecatch.png(env) $ curl https://tv.pycon.jp/_images/eyecatch.png -o source/_static/logo.png• source/conf.py ãĄńäżěäÿŃãĆŠè£¡åŁă
html_logo = "_static/logo.png"

5

PyCon JP TV #25 sample project6

Chapter 3. ãĆńãĆźãĆ£ãČđãĆďãĆž

Chapter 4markdownåŕ¿å£Ĳ
4.1 myst-parserãĆŠè£¡åŁă• https://myst-parser.readthedocs.io/en/latest/(env) $ pip install myst-parser• extensions ãĄńè£¡åŁăextensions = ["myst_parser",]

4.2 markdownãĄőãČȚãĆąãĆďãČńãĆŠè£¡åŁă• source/index.rst ãĆŠä£őæŋč.. toctree:::maxdepth: 2:caption: Contents:test• source/test.md ãĆŠè£¡åŁă(env) $ cd source(env) $ mkdir images(env) $ curl https://pbs.twimg.com/profile_images/192722095/kurokuri_400x400.jpg -o␣˓→images/takanory.jpg# ãČĘãĆźãČĹãČĽãĆŋãČěãČąãČşãČĹ* çőĞæİąæŻÿãĄŊ* çőĞæİąæŻÿãĄŊ
* [tv.pycon.jp](https://tv.pycon.jp/)(continues on next page)

7

PyCon JP TV #25 sample project(continued from previous page)![takanory](images/takanory.jpg)

8

Chapter 4. markdownåŕ¿å£Ĳ

Chapter 5ãČĘãČĳãČđãĆŠåďĽãĄĹãĆŃ
• ãČŞãČńãČĹãĆďãČşäżěåďŰãĄń3rdãČŚãČĳãČĘãĆčãČĳãĄőãČĘãČĳãČđãĄŇãĄĆãĆŃ
• Sphinx Themes Gallery5.1 Read the Docs Sphinx Theme• Read the Docs Sphinx Theme(env) $ pip install sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"

5.2 Furo• Furo(env) $ pip install furo
html_theme = "furo"9

PyCon JP TV #25 sample project10

Chapter 5. ãČĘãČĳãČđãĆŠåďĽãĄĹãĆŃ

Chapter 6

Read the DocsãĄğãČĞãČŮãČŋãĆďãĄŹãĆŃ
6.1 requirements.txtãĆŠè£¡åŁă
Listing 1: requirements.txt
furo==2022.12.7
myst-parser==0.18.1
Sphinx==5.3.0• githubãĄńpush

6.2 Read the DocsãĄőãĆćãĆńãĆęãČşãČĹèĺŋåőŽ• Read the Docs• ãĆćãĆńãĆęãČşãČĹä¡ĲæĹŘ• GitHubãĄĺéĂčæŘž

6.2.1 ãČŮãČŋãĆÿãĆğãĆŕãČĹãĆŠãĆďãČşãČİãČĳãČĹ
• pyconjptv25-sphinx-sample• https://github.com/takanory/pyconjptv25-sphinx-sample• Git• main11

PyCon JP TV #25 sample project

6.2.2 BuildãĆŠåő§èąŇ• ãČĲãĆ£ãČşãĆŠæŁĳãĄŮãĄęBuildãĆŠåő§èąŇ• WebãĄğçćžèłŊãĄğãĄŊãĆŃ https://pyconjptv25-sphinx-sample.readthedocs.io/

6.2.3 Read the DocsãĄğèęŃãĆŃãĄĺãČłãČşãĆŕãĄŇåćŮãĄĹãĄęãĆŃ• githubãĄĺãĄŃãĄőãČłãČşãĆŕãĄŇãČŽãČĳãĆÿãĄőäÿŁãĄĺäÿŃãĄńåćŮãĄĹãĄęãĄĎãĆŃ

6.3 ãČĽãĆŋãČěãČąãČşãČĹãĆŠä£őæŋčãĄŮãĄęPush
• èĞłåŃȚãĄğbuildãĄŇèțřãĆŃ

12

Chapter 6. Read the Docs ãĄğãČĞãČŮãČŋãĆďãĄŹãĆŃ

Chapter 7ãĄŁãĄŹãĄŹãĆĄæŃąåĳțæľ§èČ¡• æŃąåĳțæľ§èČ¡ãĄŇãĄĆãĆŃ
• Extensions• yoloseem/awesome-sphinxdoc: A curated list of awesome tools for Sphinx Python Documentation Generator

7.1 sphinxext-opengraph• sphinxext-opengraph 1.0 documentation• ogãĆ£ãĆřãĆŠåĚěãĆŇãĄęãĄŔãĆŇãĆŃ• çŔ¿åĲĺãĄőçŁűæĚŃãĆŠçćžèłŊ https://www.opengraph.xyz/• pip install(env) $ pip install sphinxext-opengraph• requirements.txt ãĄńè£¡åŁă...
sphinxext-opengraph==0.7.5• source/conf.py ãĄńèĺŋåőŽãĆŠè£¡åŁăextensions = [...
"sphinxext.opengraph",]# sphinxext-opengraphogp_site_url = "https://pyconjptv25-sphinx-sample.readthedocs.io/"
ogp_image = "https://pyconjptv25-sphinx-sample.readthedocs.io/en/latest/_static/logo.png"

13

PyCon JP TV #25 sample project

7.2 sphinx-copybutton• Sphinx-copybutton• ãČĘãĆŋãĆźãČĹãĄńãĆşãČĳãČĽãĆŠãĆşãČŤãČĳãĄŹãĆŃãČĲãĆ£ãČşãĆŠè£¡åŁă• pip install(env) $ pip install sphinx-copybutton• requirements.txt ãĄńè£¡åŁă...
sphinx-copybutton==0.5.1• source/conf.py ãĄńèĺŋåőŽãĆŠè£¡åŁăextensions = [...
"sphinx_copybutton",]• test.md ãĄńãĆşãČĳãČĽãĆŠè£¡åŁăfor i in range(1, 101):
match i % 3, i % 5:case (0, 0):
print("FizzBuzz")case (0, _):print("Fizz")
case (_, 0):
print("Buzz")case _:
print(i)• make htmlãĄŮãĄęãĆşãČĳãČĽãĄŇãĆşãČŤãČĳãĄğãĄŊãĆŃãĄŞãĄĺãĆŠçćžèłŊ

7.3 sphinx-design• sphinx-design• GridãĂĄTabãĂĄãĆćãĆďãĆşãČşãĄĺãĄŃãĄŇè£¡åŁăãĄğãĄŊãĆŃ
• pip install(env) $ pip install sphinx-design• requirements.txt ãĄńè£¡åŁă...
sphinx-design==0.3.0• source/conf.py ãĄńèĺŋåőŽãĆŠè£¡åŁă

14

Chapter 7. ãĄŁãĄŹãĄŹãĆĄæŃąåĳțæľ§èČ¡PyCon JP TV #25 sample projectextensions = [...
"sphinx_design",]
html_css_files = ["https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.2.1/css/all.min.css",]• Font AwesomeãĄőãČȚãĆľãČşãČĹãĆŠè£¡åŁă– Font Awesome* {fab}`twitter` @takanory* {fab}`python` Python* {fas}`cable-car` ãĆśãČĳãČŰãČńãĆńãČĳ

7.4 sphinx-pyscript• Sphinx PyScript documentation• PyScript ãĆŠå§ŃãĆĄè¿ĳãĆĄãĆŃ
• pip install(env) $ pip install sphinx-pyscript• requirements.txt ãĄńè£¡åŁă...
sphinx-pyscript==0.1.0• source/conf.py ãĄńèĺŋåőŽãĆŠè£¡åŁăextensions = [...
"sphinx_pyscript",]• markdownãĄńèĺŋåőŽãĆŠè£¡åŁă--py-config:
splashscreen:
autoclose: truepackages:- matplotlib--```{py-repl}
def fizzbuzz(num):
match i % 3, i % 5:case (0, 0):(continues on next page)

7.4. sphinx-pyscript

15

PyCon JP TV #25 sample project(continued from previous page)

return "FizzBuzz"
case (0, _):return "Fizz"case (_, 0):
return "Buzz"
case _:
return i
for i in range(1, 101):
print(fizzbuzz(i), end=", ")if i % 10 == 0:
print()
print()``````{py-terminal}```16

Chapter 7. ãĄŁãĄŹãĄŹãĆĄæŃąåĳțæľ§èČ¡

Chapter 8ãČĘãĆźãČĹãČĽãĆŋãČěãČąãČşãČĹ
• çőĞæİąæŻÿãĄŊ• çőĞæİąæŻÿãĄŊ
• tv.pycon.jp

17

PyCon JP TV #25 sample projectfor i in range(1, 101):
match i % 3, i % 5:case (0, 0):
print("FizzBuzz")case (0, _):print("Fizz")
case (_, 0):
print("Buzz")case _:
print(i)18

Chapter 8. ãČĘãĆźãČĹãČĽãĆŋãČěãČąãČşãČĹ

PyCon JP TV #25 sample project8.1 Font Awesome• @takanory• Python• ãĆśãČĳãČŰãČńãĆńãČĳ

8.2 PyScript

8.1. Font Awesome

19

PyCon JP TV #25 sample project

20

Chapter 8. ãČĘãĆźãČĹãČĽãĆŋãČěãČąãČşãČĹ

Chapter 9

Indices and tables• genindex• modindex• search21