How to the Readthedocs

The readthedocs.org (RTD) is an awesom place to host your documentation of projects in the Github as well as other repositories.

This is a simple guideline to help the GGeditor users to set up a basic project of the RTD. I have no idea if this is the best practice, it just works for me.

  1. Create a Google Docs document and bind it to the “docs/index.rst” in the Github repository.
  2. Insert markups of “toctree” table into index.rst.
  3. Create “docs/conf.py” on Github
  4. Create “docs/static/theme_overrides.css” on Github

That’s all. With the above 4 steps, you can go the RTD and create a project for your repository.

Below, I will show you how to do these steps with the GGeditor.

Step 1: Binding to the docs/index.rst

You can bind the Google Docs document with the GGeditor by menu item “Add-ons/GGeditor/Commit to Github”. Then select your repository, docs folder and the index.rst file in the dialog.

If the “index.rst” file does not exist in your Github repository, you can navigate to the “docs” folder, then click “New File” and input “index.rst”. The GGeditor will create it.

IMG1

Or select “New File” to create.

IMG2

If even the “docs” folder does not exist yet in your Github repository, you can input “docs/index.rst” as the name in the dialog of the “New File”. Like this:

IMG3

Step 2: insert toctree markup to the index.rst

The index.rst is the homepage of your project in the RTD. You can put anything you want. But you should not miss the awesome feature - the sidebar of “table of contents” for your documentation. Just simply do this in the GGeditor markup panel:

  1. Insert a “Table of Contents” from the “GGeditor Markup Panel / Markup / Directives”

IMG4

Then, the document would have a “toctree” table like this:

IMG5

You can reference the index.rst of the GGeditor for example.

Step 3: conf.py

The Github allows user to create a new file in the repository page:

IMG6

Then input the path and file name for your new file (docs/conf.py).

IMG7

Below is the content for you to copy and paste.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
# -*- coding: utf-8 -*-

from __future__ import unicode_literals
import sys, os

on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

sys.path.append(os.path.abspath(os.pardir))

__version__ = '1.0'

# -- General configuration -----------------------------------------------------

source_suffix = '.rst'
master_doc = 'index'
project = 'CHANGE-THIS'
copyright = '2016, CHANGE-THIS'

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

extlinks = {}

# -- Options for HTML output ---------------------------------------------------

html_theme = 'default'

html_static_path = ['static']

def setup(app):
    # overrides for wide tables in RTD theme
    app.add_stylesheet('theme_overrides.css') # path relative to static

"""
  You might want to uncomment the “latex_documents = []” if you use CKJ characters in your document.
  Because the pdflatex raises exception when generate Latex documents with CKJ characters.
"""
#latex_documents = []

Tip

To utilize the full power of the Sphinx, you can consult this document.

Step 4: theme_overrides.css

You can use the same way to create a new “theme_overrides.css” in the “docs/static” folder. Like this:

IMG8

Below is the content of the theme_overrides.css for you to copy and paste.

.wy-table-responsive table td, .wy-table-responsive table th {
   white-space: inherit;
}

.wy-table-responsive table th {
   background-color: #f0f0f0;
}

.line-block, .docutils.footnote {
    line-height: 24px;
}

.admonition {
    margin-bottom: 20px;
    line-height:24px;
}

.admonition > *:not(:first-child){
    /* draw a boder around a admonition */
    border-left: solid 1px #b59e9e;
    border-right: solid 1px #b59e9e;
    padding: 12px;
    margin: -12px -12px -12px -12px;
    margin-bottom: -12px !important;
}
.admonition > .last, .admonition- > .last{
    /* draw a boder around a admonition */
    border-bottom: solid 1px #b59e9e !important;
}

Because the standard theme set the white-space to be “no-wrap” for table cell undesirable for the converted table of the GGeditor.

Next Step:

Go readthedocs.org to create a project for your reStructuredText files in the Github repository.