Building Documentation with readthedocs

In this blog, I'm going to explain you how to write the Sphinx docs using reStructuredText to host in the Read the Docs.

Installing Sphinx

  $ pip install Sphinx

And we have script called sphinx-quickstart in Sphinx that sets up a source directory and creates a default conf.py with the most useful configuration values from a few questions it asks you. Just run the following command-

  $ sphinx-quickstart

Getting Started

After installing Sphinx, you will be having a master document(index.rst) created. It contains the table of contents(toctree).

You can add the documents to it like

  .. toctree::
   :maxdepth: 2

   document-name-here
   document1
   document1
   ...

Now you can add the content in those newely created documents in standard reStructuredText. There are also several features added by Sphinx.

reStructuredText (reST)

reStructuredText is an easy-to-read markup language. reStructuredText is just a plaintext that uses simple syntaxes to indicate the structure of a document.

Sections:

Section headers are created by underlining the section title

  =============== 
  Section Title        (OR)    Section Title
  ===============              ==============

  ------------------
  SubSection Title     (OR)    SubSection Title
  ------------------           -----------------

Heading levels are determined from the succession of headings

  =, for sections
  -, for subsections
  ^, for subsubsections

Paragraphs:

Paragraphs consist of blocks of left-aligned text. Blank lines separate paragraphs from each other.

  This is the first sentence in a new paragraph. This is the second sentence in a new paragraph. This is the third sentence in a new paragraph. And so on

  Second paragraph

Inline Markup

The reST inline markup is quite simple:

  *text*                      -   Renders as italics.
  **text**                    -   Renders as bold.
  reference_                  -   A single word hyperlink reference.
  `phrase reference`_         -   A hyperlink reference with spaces or punctuation.
  |substitution reference|    -   The result is substituted in from the substitution 
                                  definition. It could be text, an image, a hyperlink.
  Example:

  `word_reference`_ and `some phrase reference`_ and then a |substitution|

  .. _word_reference: http://example.org/

  .. _some phrase reference: http://somedomain.org/

  .. |build-status| image:: https://www.example.com/bird.png
    :alt: Bird

  Results -
      

word_reference and some phrase reference and then a Bird

Escaping with Backslashes

reStructuredText uses backslashes ("\") to override the special meaning given to markup characters.

  *escape* ``with`` "\"

  Results - 

  escape with ""

Lists

List Markup syntax is simple. Just place an asterisk at the start for bulleted list, place a respective number for numbered lists.


  * This is a bulleted list.
  * Bullets are "-", "*" or "+".
  * It has many items, the third item uses two or more
    lines. Continuing text must be aligned after the 
    bullet and whitespace.

      * with a nested list subitems
      * and some more subitems

  * and here the parent list continues
  * and some more parent list items

  1. This is a numbered list.
  2. It has two items too.

  #. This is also a numbered list.
  #. It has two items too.


  Note: A blank line is required before the first item and after the last item.

Source Code

Code blocks can be written by ending a paragraph with the special marker ::.

  This is a first paragraph::

    And this the code block.
    It can multiple lines.

    You can write write your code here.

  Note: A blank line is required to separate two paragraphs from each other.
  Example:

  Please see the below code::

    

Example Template

And now we are out of the code block which will normally be rendered as a paragraph.

The other way of writing code-blocks is

  .. code-block:: python or javascript or html

    $ your normal code
    $ Import, logic, html codes etc

  Example:

  .. code-block:: python

    $ git init
    $ git config user.name "Your name"

Note

  Example:

  .. note:: You can write your 'note' here. This is the note.
            It can multiple lines. 

Warning

  Example:

  .. warning:: You can write your 'warning' here.
               This is the warning message.

Posted On 24 September 2015 By MicroPyramid


Need any Help in your Project?Let's Talk

Latest Comments
Unit testing with selenium-python

Unit testing with selenium-python. Unit test case example to test the front-end

Continue Reading...
Tips to choose the best custom software development company

Choosing the best company for your software development needs is the most important step. This blog explains you tips to outsource custom software development services.

Continue Reading...
WSGI explanation with simple APP

The main goal of WSGI is to facilitate easy interconnection of servers and web frameworks/applications. WSGI defines a standerd API for web servers(uWSGI, Twisted, Gunicorn) …

Continue Reading...
Understanding self and __init__ method in python Class.

Understand self and __init__ method in python Class?
Before understanding the "self" and "__init__" methods in python class, it's very helpful if we have the idea …

Continue Reading...
List of python class special methods or magic methods

python class special methods or magic methods. magic methods allow us to override or add the default functionality of python objects. One of the biggest …

Continue Reading...
Building and Parsing XML Document using Python

Creating XML document with required elements, Then Parsing it using Python to generate a serialized form of its contents.

Continue Reading...
Working with python collections Counter

Python collections - Counter is to count the frequency of character, OrderedDict is to track the order of the contents in which they are added …

Continue Reading...
Python to Debian package: Simple, Easy and Fast

Packaging python script to debian follows strict instructions, using the following instructions, most of the steps can be skipped hence making it easy and fast.
If …

Continue Reading...
Sending SMS, MMS using Twilio.

A simple Tutorial on sending SMS and MMS in python using Twilio. In this tutorial you will learn how to send SMS, MMS and checking …

Continue Reading...
Customize and Embed Vimeo Videos using Python Requests.

Using python requests and vimeo endpoints it becomes very easy and simple to upload our videos and customize them.

Vimeo Access token:
1. Create an …

Continue Reading...
Getting Started with the IPython Notebook

IPython is a set of tools developed to make it easier for the programmers to work with Python and data. IPython provides extensions to the …

Continue Reading...
Python Arrow To Show Human Friendly Time

Arrow is a python library and command-line tool to genrerate, manipulate dates, times, timestamps.
use of arrow:
With the use of arrow, we can also create, manipulate, …

Continue Reading...
Working with python collections part 1

Python Collections - named tuple is to access by the names specified and deque is to append and pop the elements from both sides of …

Continue Reading...
Building Documentation with readthedocs

In this blog, I'm going to explain you how to write the Sphinx docs using reStructuredText to host in the Read the Docs.

Installing Sphinx

Continue Reading...
Create excel file, Insert image, Draw Bar Graphs in excel files in python using xlsxwriter

Xlsxwriter is a python module through which we can write data to Excel 2007+ XLSX file format. In this blog post we learn to write …

Continue Reading...
Integrate Twitter Social API into Django App

Integrating Twitter sign in (OAuth) in Django App, which includes
1. Capturing username via Twitter Login
2. Updating authenticated user current status on twitter(tweets).

Continue Reading...
How to implement Case Insensitive CSV DictReader in python

In general use cases we upload the CSV files to the system to store huge amount of data by uploading single file. For example in …

Continue Reading...
Python using yield and generators.

Generators are memory efficient. They allow us to code with minimum intermediate arguments, less data structures. Generators are of two types, generator expressions and generator …

Continue Reading...
Introduction to Object Oriented Programming with Python 3

Introduction to Object Oriented Programming with Python

Continue Reading...
Python Coding Techniques and Programming Practices

Coding techniques and programming practices are one of the features of a professional programmer. While writing code to solve a problem programmer should make simple …

Continue Reading...
FABRIC – LEARNING PART 2

Using Fabric, we can develop interactive script for ec2 region, ec2 flavour amazon web services. For this, you need aws account, security group, key pair, …

Continue Reading...
Generating PDF Files in Python using xhtml2pdf

There are many ways for generating PDF in python. In this post I will be presenting PDF files generation with xhtml2pdf.

xhtml2pdf: xhtml2pdf is a …

Continue Reading...
Using Python xlwt generating CSV writer and Excel files

In most of the cases, you need to export the data from your database to different formats. In this post I will show you how …

Continue Reading...
How to access development server publicly using Localtunnel

We do need to expose our local server to hit call-back URLs while programming with other APIs. There is a tool called local tunnel from …

Continue Reading...
How to generate PDF Files from HTML In Python using PDFKIT

There are many approches for generating PDF in python. pdfkit is one of the better approache as, it renders HTML into PDF with various image …

Continue Reading...
Converting Audio and Video files using FFMPEG Tool

FFMPEG is a command-line tool that converts audio or video to required formats, which handle multimedia data. It can also capture and encode in real-time.

Continue Reading...
Python Web Scraping with Beautiful soup

Download all One Piece animation series episodes by scraping site using BeautifulSoup python library.

Continue Reading...
Publishing Python Modules with PIP via PyPi

We'll install so many packages in our day to day python development. Now in this blog post, we'll try to know how to create our …

Continue Reading...
Programming with python: Decorators

Python decorators supports aspect-oriented programming. It is used to add or modify code in functions or classes. Using decorators will provide security, tracing, looking ..etc …

Continue Reading...
Vim for Python Web Development

Having a good environment setup is important for effective, fast and easy coding. We have different IDE's like eclipse, pycharm, sublime etc.. which are powerful …

Continue Reading...
Understanding Python Properties

Python Properties is a class for managing class attributes in Python. Property( ) is a built-in function that creates and returns a property object

Syntax:
attribute_name …

Continue Reading...
QRCode generation in python

A Quick Response code(QRCode) is a two-dimensional pictographic code used for its fast readability and comparatively large storage capacity. The code consists of black modules …

Continue Reading...
Understanding Audio Quality: Bit Rate, Sample Rate

Audio Quality is the accuracy and enjoyability of the audio which the user can listen from an electronic device. Audio quality depends upon the bit …

Continue Reading...
Programming with python Descriptors (_get_, _set_, _delete_) - MicroPyramid

Python descriptors are object attributes that are only invoked for new style of classes. Python descriptors comes under the category of meta programming(code that manipulates …

Continue Reading...
Debugging in Python

When something goes wrong with your code instead of using standard debugging techniques such as print statements use debugging tools. I found two great tools …

Continue Reading...
Python development environment on windows

Python is an interpreted, object-oriented, high-level programming language with dynamic semantics. Python's simple, easy to learn syntax emphasizes readability and therefore reduces the cost of …

Continue Reading...

Subscribe To our news letter

Subscribe and Stay Updated about our Webinars, news and articles on Django, Python, Machine Learning, Amazon Web Services, DevOps, Salesforce, ReactJS, AngularJS, React Native.
* We don't provide your email contact details to any third parties