Getting Started¶

Create Sphinx Project¶

$ mkdir docs-sample
$ cd docs-sample

$ sphinx-quickstart

(generates a documentation source directory and populate it with some defaults-project name, user name, version, extension(.rst preferred))

$ make html

toctree

way to connect multiple files to a single hierarchy of documents
list the items of table of content(toc) just below :maxdepth, after a blank lines.
title appeared in toctree are file’s title
maxdepth is used to indicates the depth of the tree.
toctree is automatically mirrored in the left ToC navigation bar.

.. toctree::
   :maxdepth: 2

   content1
   content2

glob: glob flag option can be used in toctree. * and ? characters are used to indicate patterns. Entries are then matched against the list of available documents and are inserted alphabetically. Also used to make title more meaningful.

.. toctree::
   :glob:

   Content 1 <content1>

content directive: generates a table of contents (TOC) in a topic. ‘depth’ indicates the max section depth to be shown in the contents

.. contents:: Table of Contents
   :depth: 2

Running the build¶

$ sphinx-build -b html sourcedir builddir

-b: selects a builder (e.g. html, dirhtml, singlehtml, text, xml)
sourcedir: source directory
builddir: directory to place the built documentation

$ make html

analyse the files in the **source/* directory and create the HTML files into the directory _build/html/ or build/html depending on configuration file*

$ make clean

clears everything within build/ directory

Compile the documentation¶

($ make - command)

$ make html
$ make latex    [Linux]
$ make.bat html [Windows]