Using Sphinx to Create Documentation with Python

While I have enjoyed my experiments with Oxygen XML Editor, the DITA workflow is not the only method that technical writers use to create documentation. In this blog, I want to explore another of my options: the Sphinx library in Python. Using Python with the Sphinx documentation generator, I'll begin to create some basic documentation with Sphinx.

I'm starting with a clean version of the newest version of Python in Windows 10. That means I'll need to install any libraries that I previously had installed. Once Python is installed, make sure the Windows PATH environment variable includes the root Python directory as well as the directory for its Scripts folder. You may also need to add to PATH the folder found at \AppData\Roaming\Python\Python310 and its Scripts folder.

I'll use the PyPl package manager to install the Sphinx library. While new versions of Python come with the PyPl library baked in, it likely isn't updated to the newest version. From the command line or PowerShell, enter:

python -m pip install --upgrade pip

Once the PyPl package manager is up to date, Sphinx is ready to be installed. Using the documentation from Sphinx as your guide, install the library:

python pip install sphinx

Once Sphinx installation is complete, use Windows Explorer to navigate to the folder that should contain the project folder for the new documentation project. Hold Shift as you right-click within the empty folder area in the Explorer window. Select "Open PowerShell window here" from the menu options.

Enter the following command line commands to create the project folder, change directories, and launch the Sphinx quickstart script:

mkdir projectname
cd projectname
sphinx.quickstart .

When the quickstart script begins, enter the settings for the new project. When in doubt, use the default setting. I chose the following:

• Root Path: I left this blank.

• Source/Build (y/n): n

• Project: Hello World

• Author: Michael Baker

• Project Release: 1

• Language: en

Once all the settings have been determined, these files will be created:

• conf.py

• index.rst

• Makefile.

Documentation pages in Sphinx are reStructuredText files (RST). The quickstart process creates the first RST file for the project, which is the project's index. The conf.py file is where to find and update settings for the project. The other batch files will be used to create the project when the text and settings are ready.

I want to create documentation for the web. I'll add some content to the index.rst file in my IDE to flesh it out a bit. Then, I'll export HTML files from the command line, navigate to the new HTML files, and open the new project from a local server:

make html
cd _build/html
python -m http.server

Python will activate the local HTTP server. Open a web browser and navigate to http://localhost:8000/. The HTML version that was created by "make html" should now be rendered by the browser.

I see some content I want to change. I go back to the IDE and change the index.rst file to update the content. I save the file and reload the web browser. The change has not been updated. I need to re-export the HTML files to include the content changes. After navigating back to the project root folder, I "make html" again. If I reload the browser, I see the text updates are rendered by the browser.

Now that I have a Sphinx workflow setup for my project, after a brief refresher on writing in reStructuredText markup format, I'll begin to flesh out my project.