How to Build an Online Project Document with VSCode, Sphinx, GitHub, and Readthedocs

Creating an online project document may seem like a daunting task, but with a bit of knowledge, it's quite straightforward. If you've ever wanted to produce a professional-looking document, take a few minutes to learn how it's done.

Below is a screenshot of a typical project document:

You can go to the link to read the detailed content:

100 Things I Wish I'd Known in My First Year in Vancouver - 100things 2.4 documentation

The source code is:

GitHub - ihenrywu/100things: 100 Things I Wish I'd Known in My First 10 Days in Vancouver

In this guide, I’ll walk you through how to create such an online project document in just 4 steps:

1. Preparation

2. Create a local rst file

3. Upload the local rst file to GitHub

4. Integrate with Readthedocs

1.1 Set Up a Virtual Environment in VSCode

If you’re just starting with Visual Studio Code (VS Code) for Python development, whether on Mac or Windows, here’s a guide to get you started:

How to use Visual Studio Code (VS Code) to set up virtual environment and code in Python—…

Once you’re ready, create a virtual environment in VSCode. I’ve named mine “venv_100things”.

python3 -m venv venv_100things

Then use the following code to activate it:

source venv_100things/bin/activate

1.2 Install the Sphinx package

First, get Sphinx:

brew install sphinx-doc

pip3 install sphinx

To verify your installation, run:

sphinx-quickstart --v

This command should return the version of Sphinx you’ve installed:

1.3 Start a Sphinx Project

Initiate a Sphinx Project using:

sphinx-quickstart

The system will prompt:

> Separate source and build directories (y/n)

Choose your preference. There will be a few follow-up questions. Provide the relevant answers.

1.4 Install the “readthedocs” theme

To install the theme:

pip3 install sphinx_rtd_theme

Then, update the conf.py file to set the theme:

html_theme = 'sphinx_rtd_theme'

1.5 Generate the requirements.txt File

pip3 freeze > requirements.txt

1.6 Create the .readthedocs.yaml file

In the project root, create a .readthedocs.yaml file. The content should resemble:

# Read the Docs configuration file for Sphinx projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the OS, Python version and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.9"
    # You can also specify other tool versions:
    # nodejs: "20"
    # rust: "1.70"
    # golang: "1.20"

# Build documentation in the "docs/" directory with Sphinx
sphinx:
  configuration: source/conf.py
  builder: html
  # Removed the output key since it's not valid

  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
  # builder: "dirhtml"
  # Fail on all warnings to avoid broken references
  # fail_on_warning: true

# Optionally build your docs in additional formats such as PDF and ePub
# formats:
#    - pdf
#    - epub

# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
  install:
  - requirements: requirements.txt

2.1 Create a rst file

The rst (reStructuredText) file is the backbone of the online document. Beside index.rst, create a new one. I've named mine `FirstThingFirst.rst`.

2.2 Update the Index with the New File

2.3 Modify the rst file

Here’s a breakdown of how an rst file might look:

First Things First
==================
.. contents:: 
   :local:
   :depth: 2

----

Study Permit
------------

The Study Permit is almost the most important document during your studies in Canada, it legitimizes your stay in this country. Don't confuse it with your student visa, which is affixed to your passport and lets you into Canada. The Study Permit is an A4-sized document you obtain when entering the country.

.. figure:: exhibit/study_visa.jpg
   :width: 300px
   :align: center

   Student Visa (stamped on your passport) [#]_

In an rst file:

• “===” denotes a primary title.
• “ — -” indicates a secondary title.

For further syntax details, refer to this rst Cheatsheet.

rst Cheatsheet - Material for Sphinx

The most popular syntax are

insert an image (in the file “exhibit”):

.. figure:: exhibit/study_visa.jpg
   :width: 300px
   :align: center

add a footnote:

Student Visa (stamped on your passport) [#]_

----

**Image Source**
   .. [#] https://en.wikipedia.org/wiki/Visa_policy_of_Canada#/media/File:Student_Visa_of_Canada_Issued_on_the_PRC_Passport_in_2015.jpg

add a note:

.. note:: 
   - `IRCC: Documents you need when you arrive in Canada <https://www.canada.ca/en/immigration-refugees-citizenship/services/study-canada/study-permit/prepare-arrival.html>`_

   - `Canadian Border Service Agency: Information for international students (PDF) <https://www.cbsa-asfc.gc.ca/publications/pub/international-students-etudiants-etrangers-eng.pdf>`_

3.1 Adding the Repository to GitHub

Within the GitHub desktop app, navigate to “Add” -> “Add Existing Repository” and select the appropriate directory.

3.2 Commit to main

3.3 Push Origin

4.1 Register a Readthedocs account

Full featured documentation deployment platform

4.2 Click “Import a Project”

4.3 Choose the corresponding project in GitHub

4.4 Click “Build version”

4.5 Click “View Docs”

5 Generate PDF

Install mactex package:

brew install --cask mactex            

sudo tlmgr update --self

Set parameterlatex_engine and latex_elements in con.py file.

latex_engine = 'xelatex'
latex_elements = {
    'papersize': 'a4paper',
    'pointsize': '11pt',
    'preamble': r'''
\usepackage{xeCJK}
\setCJKmainfont[BoldFont=STZhongsong, ItalicFont=STKaiti]{STSong}
\setCJKsansfont[BoldFont=STHeiti]{STXihei}
\setCJKmonofont{STFangsong}
\XeTeXlinebreaklocale "zh"
\XeTeXlinebreakskip = 0pt plus 1pt
\parindent 2em
\definecolor{VerbatimColor}{rgb}{0.95,0.95,0.95}
\setcounter{tocdepth}{3}
\renewcommand\familydefault{\ttdefault}
\renewcommand\CJKfamilydefault{\CJKrmdefault}
'''
}

run the code:

make latexpdf

One More Thing

If you want to build a multi-language version, here is a handbook:

https://ihenrywu.medium.com/how-to-create-a-readthedocs-online-document-in-multiple-languages-dbdc1e67068d

Wrote by Henry Wu, polished by ChatGPT.

Photo by Wesley Tingey on Unsplash