创建文档¶

This section covers the basics of how to create documentation using Sphinx and host the documentation for free in Read The Docs.

Installing Sphinx¶

Use pip to install Sphinx:

Unix/macOS

python3 -m pip install -U sphinx

Windows

py -m pip install -U sphinx

For other installation methods, see this installation guide by Sphinx.

Create a docs directory inside your project to hold your documentation:

cd /path/to/project
mkdir docs

Run sphinx-quickstart inside the docs directory:

cd docs
sphinx-quickstart

This sets up a source directory, walks you through some basic configurations, and creates an index.rst file as well as a conf.py file.

You can add some information about your project in index.rst, then build them:

make html

For more details on the build process, see this guide by Read The Docs.

For a more detailed guide on how to use Sphinx and reStructuredText, please see this documentation tutorial on Hitchhiker’s Guide to Python.