This repository is an updated version for Brandon Rhodes's Sphinx tutorial presented at PyCon every year from 2010 through 2013. The original tutorial was written for Python 2 using Sphinx 1.x, and has not been updated since 2013. Since Python 3 has entirely replaced Python 2 now, I have updated the Sphinx code in the tutorial to make it Python 3 compatible, and have added some new components to the code to make it look more close to real projects.

It is strongly recommended to watch Brandon Rhodes's Sphinx tutorial session at PyCon 2013, since I have not found any other tutorial videos or blogs are as good as his even though it is year 2020 now. Most of the content he presented is still applicable to Python 3 and the latest Sphinx, and the reStructuredText was covered sufficiently in depth for writing documentations for Sphinx.

This repository would be useful as a reference for documentation with Python 3 and Sphinx, provided that we have taken Brandon Rhodes's Sphinx tutorial session. There is also a short blog post on this on my website.

.
├── docs
│   ├── make.bat
│   ├── Makefile
│   ├── README.md
│   └── source
│       ├── api.rst
│       ├── conf.py
│       ├── examples.rst
│       ├── guide.rst
│       ├── index.rst
│       ├── _static
│       ├── _templates
│       └── tutorial.rst
├── examples
│   ├── 00-create_triangle
│   │   ├── create_triangle.py
│   │   └── README.md
│   └── README.md
├── LICENSE.md
├── README.md
├── requirements.txt
├── setup.py
└── trianglelib
    ├── __init__.py
    ├── shape.py
    ├── tests.py
    └── utils.py

The trianglelib used for the tutorial has no dependency. But for completeness, we added setuptools and sphinx to our requirements.txt.

To install the dependencies, please run the following command in the terminal.

$ pip install -r requirements.txt

To install the trianglelib, which we would not probably do, please run the following command in the terminal.

$ pip install .

Please check the README in docs for details.

Go to Read the Docs and follow the instructions to publish the documentations. The latest version of the documentation of this repo could be found on TriangleLib's Documentation. Use GitHub tags for version control on Read the Docs.

• Brandon Rhodes's Sphinx Tutorial
• Brandon Rhodes's Sphinx Tutorial Session at PyCon 2013
• Python Documentation Using Sphinx