Documentation Guide¶

reStructuredText & ReadTheDocs documentation online guide

Installation on Windows¶

Refer to Read the Docs user documentation
Helpful screencast: Sphinx & Read the Docs

Install Python¶

download Python windows installer

(Optional) Install Babun¶

download Babun windows shell

Using reStructuredText¶

install sphinx:

$ pip install sphinx sphinx-autobuild
$ pip install sphinx-rtd-theme

make ‘docs’ directory:

$ cd <project-dir>
$ mkdir docs

run a script:

$ sphinx-quickstart

edit & build your documents:

$ make html

open in browser:

$ open build/html/index.html

Import to Read the Docs¶

To import a repository, Sign up Read the docs & visit your dashboard.
Click Import a project and Import Manually.
Input Project Details including repository URL.
For example, https://github.com/seungin/docs.git

Connect with Github Repository¶

Go to repository settings
Click Integrations & services and Add services
Select Read the Docs

reStructuredText Cheet Sheet¶

syntax description for reStructuredText

Reference¶

(Recommended) rest-sphinx-memo
reStructuredText Primer

Paragraphs¶

The paragraph is the most basic block in a reST document.
Separated by one or more blank lines.
Indentation is significant in reST, a paragraph must have same level of indentation.

Inline Markup¶

one asterisk means ltalic, *text* -> text
two asterisk means bold, **text** -> text
backquotes means code sample, ``text`` -> text

Restrictions¶

It cannot be nested.
It cannot start or end with whitespace: * text* is wrong.

Interpreted Text Roles¶

reST also allows for custom interpreted text roles.
Signify that the enclosed text should be interpreted in a specific way.
Sphinx uses this to provide semantic markup and cross-referencing of identifiers.
See Inline markup for roles added by Sphinx.

Lists and Quote-like Blocks¶

Basic Lists¶

bulleted lists use several signs (*, -, +, …)
numbered lists use number itself (1, 2, …)
auto-numbered lists use # sign

* bulleted list item
* bulleted list item

1. numbered list item
2. numbered list item
#. auto-numbered list item
#. auto-numbered list item

bulleted list item
bulleted list item

numbered list item
numbered list item
auto-numbered list item
auto-numbered list item

Nested Lists¶

nested lists must be seperated by blank lines

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

this is
a list
- with a nested list
- and some subitems
and here the parent list continues

Definition Lists¶

use indentation

term #1
  Definition of the term #1
  which must be indented

  multiple paragraphs are possible

term #2
  Definition of the term #2

term #1

Definition of the term #1 which must be indented

multiple paragraphs are possible

term #2

Definition of the term #2

Quoted Paragraphs¶

use a blank line and indentation

main paragraph

  quoted paragraphs
  quoted paragraphs

main paragraph (continues)

main paragraph

quoted paragraphs quoted paragraphs

main paragraph (continues)

Line Blocks¶

use a blank line and line breaks

main paragraph

| quoted paragraphs
| quoted paragraphs
|

main paragraph (continues)

main paragraph

quoted paragraphs
quoted paragraphs

main paragraph (continues)

Source Code¶

Literal Code Blocks¶

by ending with :: and indentation

normal text paragraph::

  source code paragraph except
  that the indentation is removed

  it can span multiple lines

nomal text paragraph (continues)

normal text paragraph:

source code paragraph except
that the indentation is removed

it can span multiple lines

nomal text paragraph (continues)

Smart Conversion Rules¶

if preceded by whitespace, :: is removed
if preceded by non-whitespace, :: is replaced by a single colon :

with colon::

  source code paragraph

without colon ::

  source code paragraph

with colon:

source code paragraph

without colon

source code paragraph

Syntax Highlighting¶

sphinx supports by
- .. sourcecode:: language
- .. code-block:: language

.. sourcecode:: cpp

  int main() {
    printf("Hello, World!");
    return 0;
  }

.. code-block:: python

  print('Hello, Python!')

int main() {
  printf("Hello, World!");
  return 0;
}

print('Hello, Python!')

Code¶

Here is some python code example.:

print 'hello'
>> hello

Other Languages¶

Here is some c++ code example.

int main() {
    std::cout << "Hello, World!" << '\n';
    return 0;
}

int main() {
    std::cout << "Hello, World!" << '\n';
    return 0;
}

License¶

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contact¶

If you have some trouble please email seungin.cha@gmail.com