RST Workshop: Development Environment

The development environment for this workshop consists of:

Environment Setup

  1. Install Visual Studio Code.

  2. Install reStructuredText Extension for Visual Studio Code.

  3. Open a Linux shell and install Sphinx and the required extensions.

    sudo apt-get update && sudo apt upgrade
sudo apt-get -y install python3-pip
pip3 install Sphinx
pip3 install sphinx-autobuild

Create a Project

  1. Create a project directory

  2. Use sphinx-quickstart to create a new Sphinx projects

    • Open a terminal in VSC (Terminal -> New Terminal)

    • Open up a linux shell

    • Execute: sphinx-quickstart

    • Follow the prompts

Configure LiveReload

  1. Clone sphinx-server from https://github.com/dldl/sphinx-server.

    Note

    This project needs to be in /opt/sphinx-server

    cd /opt
sudo git clone https://github.com/dldl/sphinx-server.git

  2. Copy file server.py to your project root.

    cd /mnt/c/Users/user/source/rst/my-project
cp /opt/sphinx-server/server.py .

  3. Start the mini-server that uses autobuild and livereload.

    python3 server.py

    python3 only

    Using python will generate this error:

    python server.py
Traceback (most recent call last):
  File "server.py", line 7, in <module>
    import http.server
ImportError: No module named http.server

    Tip

    Start python3 server.py using the built-in terminal in VSC!

    1. Terminal -> New Terminal

    2. bash

    3. python3 server.py

  4. Open your browser to http://localhost:8000/.