Sphinx Introduction

What is Sphinx?

Practical Example

• Python Documentation
• Django Documentation
• Python Module of the Week

Dig to deeper articles of Python Doc,
and click "Show Source" on the sidebar

Why use Sphinx?

• Plain Text Source
• Put in VCS Repository
• Pure HTML to Deploy

Plain Text Source

Use reStructuredText as Markup Syntax,
write down easily!

source file name could be *.rst or *.txt

Put in VCS Repository

Plain Text is good for version control system.

Pure HTML to Deploy

use make html to render the output.

Install Sphinx

On Ubuntu

sudo apt-get install
python-sphinx

On Fedora

sudo yum install
python-sphinx

On Windows

• Install Python 2.7
• Install setuptools

Setup environment variables

PYTHON_HOME

C:\Python27

PATH

…;%PYTHON_HOME%;
%PYTHON_HOME%\Scripts

Setup proxy in cmd

(if needed)

set http_proxy=
http://99092033:password
@10.243.17.220:80/

Install Sphinx package in cmd

easy_install -U sphinx

Let's try it

$ mkdir docs

$ cd docs

$ sphinx-quickstart

Sphinx Quickstart

Say "Yes" to separate source and build directories.

Use the source, Luke!

$ make html

source/conf.py

source_suffix = '.rst'

master_doc = 'index'

project = u'DEMO'

copyright = u'2012, Mike'

version = '0.1'

release = '0.1 alpha'

html_theme = 'default'

source/index.rst

.. toctree::
   :maxdepth: 2
   
   intro
   chapter1
   chapter2
	

reStructuredText Syntax

Practice reStructuredText

Online reStructuredText editor

Open it first, try and practice the following.

Here merely introduces some
which is often used.

Paragraphs

Paragraphs are simply chunks
of text separated by one or
more blank lines.

all lines of the same
paragraph must be 
left-aligned to the same
level of indentation.
	

Section

=================
This is a heading
=================

Sub heading
-----------

This is content.
	

Inline markup

• one asterisk:
  *text* for emphasis (italics)
• two asterisks:
  **text** for strong emphasis (boldface)
• backquotes:
  ``text`` for code samples.

Bulleted Lists & Definition Lists

* This is a ``bulleted`` list.
* It has two items, the
  **second** uses two lines.
* *third* item

Kitty
  Little cat.

Puppy
  Little dog.
	

Numbered Lists

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

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

Nested Lists

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list
  continues
	

Source Code

The next paragraph is 
a code sample::

	import os
 
	text="HelloWorld_Text"
	print(text)

It's a normal paragraph again.
	

Hyperlinks

`Link <http://example.com/>`_
for inline web links.

Or separate the link and the target definition:

This is a paragraph that
contains `a link`_.

.. _a link: http://example.com/
	

Footnotes

[#]_ is a reference 
to footnote 1, 
and [#]_ is a reference
to footnote 2.

.. [#] This is footnote 1.
.. [#] This is footnote 2.
	

Table

+------------+-------+-------+
| Header rows| Head 2| Head 3|
| (optional) |       |       |
+============+=======+=======+
| body row 1 | col 2 | col 3 | 
+------------+-------+-------+
| body row 2 | ...   | ...   |
+------------+-------+-------+
	

Simple Table

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======
	

reStructuredText Directive

Table

.. table:: Truth table

   =====  =====
     A    not A
   =====  =====
   False  True
   True   False
   =====  =====
	

CSV Table

.. csv-table:: Price!
   :header: "item", "$", "?"
   :widths: 15, 10, 30

   "A", 2.99, "expensive"
   "B", 1.49, "cheap"
   "C", 1.99, "modest"
	

List Table

.. list-table:: Price!
   :header-rows:  1
   :widths: 15, 10, 30
   
   * - item
     - $
     - ?
   * - A
     - 2.99
     - expensive
	

Image

.. image:: picture.jpeg
   :height: 100px
   :width: 200 px
   :scale: 50 %
   :alt: alternate text
   :align: right
	

Topic

.. topic:: Topic Title

    Subsequent indented lines
    comprise the body of the
    topic, and are interpreted
    as body elements.
	

Sidebar

.. sidebar:: Sidebar Title
   :subtitle: Optional Subtitle

   Subsequent indented lines
   comprise the body of the
   sidebar, and are interpreted
   as body elements.
	

Header & Footer

.. header:: Space for Rent.

Elevator down

.. footer:: No Place Like Home.
	

Sphinx Inline Markup

Cross-referencing location

.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself,
see :ref:`my-reference-label`.
	

Cross-referencing documents

Link Caption

Referencing downloadable files

:download:`script <../demo.py>`
	

All downloadable files are put into the _downloads subdirectory of the output directory

Sphinx Paragraph-level markup

Tables of Contents

.. toctree::
   :numbered:
   :titlesonly:
   
   foo
   bar
	

Note

.. note::

   This function is not usable
   for current release.
	

Warning

.. warning::

   We are under attack!
	

Version

.. versionadded:: 2.5
   The *spam* parameter.
  
.. versionchanged:: 2.6
   Merge the *trash* parameter.
   
.. deprecated:: 3.0
   We have a **trash can** now.
	

See Also

.. seealso::

   Chapter 1
      Documentation of the foo.

   Chapter 2
      Documentation for far.
	

See Also Short Form

.. seealso:: next page

Rubric

.. rubric:: title

This directive creates a
paragraph heading that is
not used to create a table
of contents node. 
	

Horizontal List

.. hlist::
   :columns: 3

   * A list of
   * short items
   * that should be
   * displayed
   * horizontally
	

Reference

• reStructuredText Primer
• reStructuredText Directives
• Sphinx Inline Markup
• Sphinx Paragraph-level markup

Other Lightweight Markup Language

• Markdown
• Textile

End!

by kidwm

http://kidwm.net/