Good tools are prerequisite to the successful execution of a job. – old Chinese proverb
1.1.1. About this tutorial¶
This document is a summary of my valueable experiences in using Python decumentation
Github webpage. The PDF version can be downloaded from HERE. You may download and distribute it. Please be aware, however, that the note contains typos as well as inaccurate or incorrect description.
In this repository, I try to use the detailed demo code and
examples to show how to use
Sphinx to generate the
Github. If you find your work wasn’t cited in this note, please feel free to let me know.
Although I am by no means a python programming and Sphinx expert, I decided that it would be useful for me to share what I learned about Sphinx in the form of easy tutorials with detailed example. I hope those tutorials will be a valuable tool for your studies.
The tutorials assume that the reader has a preliminary knowledge of
Linux. And this document is generated automatically by using sphinx.
1.2. Motivation for this tutorial¶
Sphinx is an awesome Python documentation package, and it has excellent facilities for the documentation of software projects in a range of languages. I have been using
Sphinx for almost 4 years. I was impressed and attracted by Sphinx in the first using. And I foud that:
- It supports several popular output formats:
HTML(including Windows HTML Help),
LaTeX(for printable PDF versions), ePub, Texinfo, manual pages, plain text.
- It has easy publishing routes: Github.
- Is has extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information
- It has hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children.
- It has automatic indices: general index as well as a language-specific module indices
- It has awesome code handling: automatic highlighting using the Pygments highlighter
- Is has abundant extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more
- It has abundant contributed extensions: more than 50 extensions contributed by users in a second repository; most of them installable from PyPI