Merge pull request #197 from pyconjp/ISSHA-2743-rest2markdown

ISSHA-2743 reST から markdown にする

README.md

@@ -24,3 +24,11 @@ $ . env/bin/activate
 2. forkしたリポジトリをcloneする
 3. cloneしたリポジトリのmasterに、修正したテキスト内容をpushする
 4. PRを作成する
+
+## reStructuredTextとmarkdownについて
+
+* Python Boot Campテキスト(`source/textbook/` 以下)と貢献者一覧ページ(`source/organize/3_contributers.md`)はmarkdownで記述しています
+  * markdownはSphinxの拡張表現(directive)に対応した**MyST**を使っています
+  * MySTの記述ルールについては[myst-parser](https://myst-parser.readthedocs.io/)を参照してください
+  * とはいえ、directiveを使わないのであれば通常のmarkdownと同じです
+* それ以外のページはreStructuredTextで記述しています

requirements.txt

@@ -1,4 +1,5 @@
 furo==2022.12.7
-Sphinx==6.0.0
+myst-parser[linkify]==0.18.1
+Sphinx==5.3.0
 sphinx-copybutton==0.5.1
-sphinxext-opengraph==0.7.4
+sphinxext-opengraph==0.7.5

source/conf.py

@@ -28,6 +28,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'myst_parser',
     'sphinx_copybutton',
     'sphinxext.opengraph',
 ]
@@ -59,6 +60,14 @@
 
 numfig = True
 
+# see: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-extensions
+myst_enable_extensions = [
+    "colon_fence",
+    "linkify",
+]
+
+# see: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#linkify
+myst_linkify_fuzzy_links = False
 
 # -- Options for HTML output -------------------------------------------------
 

source/organize/3_contributers.md

@@ -0,0 +1,27 @@
+# 貢献者一覧
+
+Python Boot Campのテキスト作成には以下の人たちが関わっています。
+
+- [takanory](https://github.com/takanory)
+- [Akira-Taniguchi](https://github.com/Akira-Taniguchi)
+- [ryu22e](https://github.com/ryu22e)
+- [terapyon](https://github.com/terapyon)
+- [shimizukawa](https://github.com/shimizukawa)
+- [ryokamiya](https://github.com/ryokamiya)
+- [HayaoSuzuki](https://github.com/HayaoSuzuki)
+- [kazweda](https://github.com/kazweda)
+- [rhoboro](https://github.com/rhoboro)
+- [jbking](https://github.com/jbking)
+- [kashewnuts](https://github.com/kashewnuts)
+- [qt-luigi](https://github.com/qt-luigi)
+- [tell-k](https://github.com/tell-k)
+- [drillan](https://github.com/drillan)
+- [koedoyoshida](https://github.com/koedoyoshida)
+- [max747](https://github.com/max747)
+- [ymyzk](https://github.com/ymyzk)
+- [ikura1](https://github.com/ikura1)
+- [hikaruya8](https://github.com/hikaruya8)
+- [kobatomo](https://github.com/KobaTomo/)
+- [kuma127](https://github.com/kuma127)
+- [hamukazu](https://github.com/hamukazu)
+- [Takeshi_Izawa](https://github.com/zxb04116)

source/textbook/1_install.rst → source/textbook/1_install.md

@@ -1,10 +1,10 @@
-.. _guide-install:
+(guide-install)=
 
-======================
- Pythonをはじめる前に
-======================
+# Pythonをはじめる前に
 
-:節サブタイトル: エディタ、コマンドラインの準備、Pythonのインストール方法の紹介
+```{admonition} 節サブタイトル
+エディタ、コマンドラインの準備、Pythonのインストール方法の紹介
+```
 
 Pythonをはじめましょう！
 
@@ -14,122 +14,126 @@ Pythonをはじめましょう！
 - Python を実行するためのコマンドラインの準備
 - Pythonのインストール方法
 
-.. index:: Editor
-    single: Editor; VS Code
+```{index} Editor single: Editor; VS Code
+```
+
+## エディタの準備
 
-エディタの準備
-==============
 ソースコードを読み書きするために、エディタを用意します。
 普段使用しているエディタがある人は、そのエディタを使用して構いません。
 Python の文法に対応しているエディタを使用することをおすすめします。
 
-普段使っているエディタがない人は、 `Visual Studio Code <https://code.visualstudio.com/>`_ をインストールしてください。
+普段使っているエディタがない人は、 [Visual Studio Code](https://code.visualstudio.com/) をインストールしてください。
 Visual Studio Codeはさまざまなプログラミング言語に対応したエディタで、拡張機能も豊富です。
 
 Visual Studio CodeとPython用拡張機能のインストール手順は以下のページを参考にしてください。
 
-* `IDE(エディタ) — Pythonスターターガイド ドキュメント <https://starter-guide.od.pythonic-exam.com/ja/latest/ide/index.html>`_
-* `Visual Studio Codeのインストール: Visual Studio Code でPython入門 【Windows編】 - python.jp <https://www.python.jp/python_vscode/windows/setup/install_vscode.html>`_
+- [IDE(エディタ) — Pythonスターターガイド ドキュメント](https://starter-guide.od.pythonic-exam.com/ja/latest/ide/index.html)
+- [Visual Studio Codeのインストール: Visual Studio Code でPython入門 【Windows編】 - python.jp](https://www.python.jp/python_vscode/windows/setup/install_vscode.html)
+
+```{index} Terminal
+```
 
-.. index:: Terminal
+## ターミナルの準備
 
-ターミナルの準備
-================
 Python を実行するために、ターミナル(macOS)、PowerShell(Windows)または、Visual Studio Code 内のターミナルを立ち上げます。
 
 - macOS では「アプリケーション」→「ユーティリティ」→「ターミナル」を選択します
-- Windows では **Windows+R** キーを押して ``powershell`` と入力します
+- Windows では **Windows+R** キーを押して `powershell` と入力します
 - Visual Studio Codeではメニューから「表示」→「ターミナル」を選択します
 
-.. index:: Install
+```{index} Install
+```
 
-.. _python-install:
+(python-install)=
 
-Pythonのインストール
-====================
+## Pythonのインストール
 
 ここではPythonのインストール方法を説明します。
 
 macOS、Windows、Linuxの3つの環境でのインストール手順を説明します。
 
-.. index::
-    single: Install; macOS
+```{index} single: Install; macOS
+```
+
+### macOSの場合
 
-macOSの場合
------------
 macOSでPythonを利用する場合は、Pythonの公式サイトで配布されているビルド済みのパッケージをインストールします。
 
-「 `Python Release Python 3.10.8 <https://www.python.org/downloads/release/python-3108/>`_ 」をブラウザで開きます。
+「 [Python Release Python 3.10.8](https://www.python.org/downloads/release/python-3108/) 」をブラウザで開きます。
 以下をダウンロードして実行し、Pythonをインストールします。
 
-- `macOS 64-bit universal2 installer <https://www.python.org/ftp/python/3.10.8/python-3.10.8-macos11.pkg>`_
+- [macOS 64-bit universal2 installer](https://www.python.org/ftp/python/3.10.8/python-3.10.8-macos11.pkg)
 
-詳しくはPythonの公式ドキュメントの「 `Using Python on a Mac <https://docs.python.org/ja/3/using/mac.html>`_ 」を参考にしてください。
+詳しくはPythonの公式ドキュメントの「 [Using Python on a Mac](https://docs.python.org/ja/3/using/mac.html) 」を参考にしてください。
 
-インストールが完了したらPythonのバージョンが3.10.8になっていることを確認します（:numref:`check-version-mac`）。
+インストールが完了したらPythonのバージョンが3.10.8になっていることを確認します（{numref}`check-version-mac`）。
 
-.. _check-version-mac:
+(check-version-mac)=
 
-.. code-block:: bash
-   :caption: Pythonのバージョンを確認
+```{code-block} bash
+:caption: Pythonのバージョンを確認
 
-   $ python3 -V
-   Python 3.10.8
+$ python3 -V
+Python 3.10.8
+```
 
-.. index::
-    single: Install; Windows
+```{index} single: Install; Windows
+```
 
-Windowsの場合
--------------
+### Windowsの場合
 
 WindowsでPythonを利用する場合は、Pythonの公式サイトで配布されているWindowsインストーラを利用します。
 
-「 `Python Release Python 3.10.8 <https://www.python.org/downloads/release/python-3108/>`_ 」をブラウザで開きます。
+「 [Python Release Python 3.10.8](https://www.python.org/downloads/release/python-3108/) 」をブラウザで開きます。
 OSによって以下のいずれかのインストーラーをダウンロードし、ウィザードに従ってインストールします。
 
-- 64ビット版: `Windows installer (64-bit) <https://www.python.org/ftp/python/3.10.8/python-3.10.8-amd64.exe>`_
-- 32ビット版: `Windows installer (32-bit) <https://www.python.org/ftp/python/3.10.8/python-3.10.8.exe>`_
+- 64ビット版: [Windows installer (64-bit)](https://www.python.org/ftp/python/3.10.8/python-3.10.8-amd64.exe)
+- 32ビット版: [Windows installer (32-bit)](https://www.python.org/ftp/python/3.10.8/python-3.10.8.exe)
 
-この時、「Add python.exe to PATH」にチェックを入れておきましょう。自動的に必要な環境変数が設定されます（:numref:`windows-install`）。
+この時、「Add python.exe to PATH」にチェックを入れておきましょう。自動的に必要な環境変数が設定されます（{numref}`windows-install`）。
 
-.. _windows-install:
+(windows-install)=
 
-.. figure:: images/pythonforwindows1.png
-   :width: 600
+```{figure} images/pythonforwindows1.png
+:width: 600
 
-   Python for Windowsのインストール画面
+Python for Windowsのインストール画面
+```
 
-.. index::
-    single: Install; Linux
+```{index} single: Install; Linux
+```
 
-インストールが完了したらPythonのバージョンが3.10.8になっていることを確認します（:numref:`check-version-win`）。
+インストールが完了したらPythonのバージョンが3.10.8になっていることを確認します（{numref}`check-version-win`）。
 
-.. _check-version-win:
+(check-version-win)=
 
-.. code-block:: doscon
-   :caption: Pythonのバージョンを確認
+```{code-block} doscon
+:caption: Pythonのバージョンを確認
 
-   C:\Users\user>python -V
-   Python 3.10.8
+C:\Users\user>python -V
+Python 3.10.8
+```
+
+### Linux（Ubuntu Server）の場合
 
-Linux（Ubuntu Server）の場合
-----------------------------
 Ubuntu 22.04にはデフォルトでPython 3.10.8がインストールされています。
-以下のコマンドでPythonのバージョンを確認します（:numref:`check-version`）。
+以下のコマンドでPythonのバージョンを確認します（{numref}`check-version`）。
+
+(check-version)=
 
-.. _check-version:
+```{code-block} bash
+:caption: Pythonのバージョンを確認
 
-.. code-block:: bash
-   :caption: Pythonのバージョンを確認
+$ python3 -V
+Python 3.10.8
+```
 
-   $ python3 -V
-   Python 3.10.8
+## 注意事項
 
-注意事項
-========
 これ以降の本テキストでは上記手順でインストールしたPython 3.8以降を使用することを前提に記載しています。
 
-Python 2.7等のPython2系やAnacondaでインストールしたPython、または `Jupyter <https://jupyter.org/>`_ や `Google Colaboratory <https://colab.research.google.com/?hl=ja>`_ では実習ができません。
+Python 2.7等のPython2系やAnacondaでインストールしたPython、または [Jupyter](https://jupyter.org/) や [Google Colaboratory](https://colab.research.google.com/?hl=ja) では実習ができません。
 
 Pythonを起動した時に表示される文字をチェックして、下記が問題ないか確認してください。
 
@@ -138,7 +142,7 @@ Pythonを起動した時に表示される文字をチェックして、下記
 
 インストールされていない場合は前述の手順でPython3.10.8のインストールを行ってください。
 
-まとめ
-======
+## まとめ
+
 本節では、事前準備としてエディタ、コマンドラインとPython のインストール方法を紹介しました。
 次節ではFizzBuzzを通じたPythonの特徴、基本、役立つWeb の情報、書籍を紹介します。