Background¶
By Lex Li
What is reStructuredText?¶
Below is the definition quoted from the Docutils homepage.
“reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. reStructuredText is designed for extensibility for specific application domains. The reStructuredText parser is a component of Docutils. reStructuredText is a revision and reinterpretation of the StructuredText and Setext lightweight markup systems.”
“The primary goal of reStructuredText is to define and implement a markup syntax for use in Python docstrings and other documentation domains, that is readable and simple, yet powerful enough for non-trivial use. The intended purpose of the markup is the conversion of reStructuredText documents into useful structured data formats.”
Note
Though Markdown has now become almost the standard of documentation markup, reStructuredText still has its own territory.
You can find a lot of information about reStructuredText from Docutils.
What is Sphinx?¶
Below is the definition quoted from the Sphinx homepage.
“Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.”
“It was originally created for the Python documentation, and it has excellent facilities for the documentation of software projects in a range of languages. Of course, this site is also created from reStructuredText sources using Sphinx! The following features should be highlighted:”
Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text
Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information
Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
Automatic indices: general index as well as a language-specific module indices
Code handling: automatic highlighting using the Pygments highlighter
Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more
Contributed extensions: more than 50 extensions contributed by users in a second repository; most of them installable from PyPI
“Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.”
Note
Hosting sites such as ReadTheDocs help make Sphinx popular.
What is Visual Studio Code?¶
Visual Studio Code (VS Code for short) is a free and open source code editor from Microsoft.
According to various surveys such as Stack Overflow Developer Survey, Visual Studio Code is now the most popular editor around the world.
What is Esbonio?¶
Esbonio project develops a VS Code extension as well as a language server that builds upon Sphinx engine. It provides very important functionalities such as live preview and IntelliSense.