Getting Started with Read the Docs

getting Started

This article will show you how to use Read the Docs. You can import your documents into Read the Docs in under 5 minutes and present them beautifully for the world.

If you already use Sphinx or Markdown for your document, skip directly to Importing your document .

write documentation

You have two ways to format your document:

• Using reStructuredText
• Use Markdown

reStructuredText

There is a screen recording that can help you if you want.

Sphinx is a tool that makes it easy to create beautiful documentation. Assuming you already have Python , install Sphinx :

$ pip install sphinx sphinx-autobuild

Create a directory in your project to hold your documents:

$ cd /path/to/project
$ mkdir docs

run there sphinx-quickstart:

$ cd docs
$ sphinx-quickstart

The quickstart will walk you through creating some basic configurations, in general, you can use the defaults. When you're done, you'll have one index.rst, one, conf.pyand some other files. Add them to version control.

Now, edit yours index.rstand add some information about your project. Include as much detail as possible (see reStructuredText syntax or this template if you need help ). Build them to see how they look:

$ make html

Note

You can usesphinx-autobuildautomatic reloading of documents. run insteadsphinx-autobuild . _build/html.

Edit your files and rebuild until you like what you see, then commit your changes and push to your public repository. Once you have your Sphinx documentation stored in a public repository, you can start using "Read the Docs".

Markdown

You can use both Markdown and reStructuredText in the same Sphinx project. Read the Docs supports this, you can do this locally:

$ pip install recommonmark

Then in your conf.pyadd:

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

Note that

Markdown does not support many features of Sphinx, such as inline markup and directives. However, it works for basic prose content. reStructuredText is the preferred format for technical documentation, read this blog post .