Skip to content

Commit ccfd92e

Browse files
committed
First pass at Sphinx documentation. Most of it still needs to be written :)
1 parent a686a5a commit ccfd92e

16 files changed

+1697
-0
lines changed

doc/.static/sphinx.png

33.2 KB
Loading

doc/.templates/index.html

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
{% extends "layout.html" %}
2+
{% set title = 'Overview' %}
3+
{% block body %}
4+
<h1>Welcome</h1>
5+
6+
<p>
7+
Sphinx is a tool that makes it easy to create intelligent and beautiful
8+
documentation for Python projects, written by Georg Brandl. It was
9+
originally created to translate <a href="http://docs.python.org/dev/">the
10+
new Python documentation</a>, but has now been cleaned up in the hope that
11+
it will be useful to many other projects. (Of course, this site is also
12+
created from reStructuredText sources using Sphinx!)
13+
</p>
14+
<p>
15+
Although it is still under constant development, the following features are
16+
already present, work fine and can be seen &#8220;in action&#8221; in the
17+
Python docs:
18+
</p>
19+
<ul>
20+
<li><b>Output formats:</b> HTML (including Windows HTML Help) and LaTeX, for
21+
printable PDF versions</li>
22+
<li><b>Extensive cross-references:</b> semantic markup and automatic links
23+
for functions, classes, glossary terms and similar pieces of information</li>
24+
<li><b>Hierarchical structure:</b> easy definition of a document tree, with
25+
automatic links to siblings, parents and children</li>
26+
<li><b>Automatic indices:</b> general index as well as a module index</li>
27+
<li><b>Code handling:</b> automatic highlighting using the <a
28+
href="http://pygments.org">Pygments</a> highlighter</li>
29+
</ul>
30+
<p>
31+
Sphinx uses <a href="http://docutils.sf.net/rst.html">reStructuredText</a>
32+
as its markup language, and many of its strengths come from the power and
33+
straightforwardness of reStructuredText and its parsing and translating
34+
suite, the <a href="http://docutils.sf.net/">Docutils</a>.
35+
</p>
36+
37+
<h2>Documentation</h2>
38+
<table class="contentstable" align="center" style="margin-left: 30px"><tr>
39+
<td width="50%">
40+
<p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents</a><br>
41+
<span class="linkdescr">for a complete overview</span></p>
42+
<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br>
43+
<span class="linkdescr">search the documentation</span></p>
44+
</td><td width="50%">
45+
<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br>
46+
<span class="linkdescr">all functions, classes, terms</span></p>
47+
<p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">Module Index</a><br>
48+
<span class="linkdescr">quick access to all documented modules</span></p>
49+
</td></tr>
50+
</table>
51+
52+
<h2>Get Sphinx</h2>
53+
<p>
54+
Sphinx is available as an <a
55+
href="http://peak.telecommunity.com/DevCenter/EasyInstall">easy-install</a>able
56+
package on the <a href="http://pypi.python.org/pypi/Sphinx">Python Package
57+
Index</a>.
58+
</p>
59+
60+
{% endblock %}

doc/.templates/indexsidebar.html

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<h3>Download</h3>
2+
3+
<p>Get Sphinx from the <a href="http://pypi.python.org/pypi/Sphinx">Python Package
4+
Index</a>.</p>
5+
6+
<h3>Questions? Suggestions?</h3>
7+
8+
<p>Send them to <nobr>&lt;georg at python org&gt;</nobr>, or come to the
9+
<tt>#python-docs</tt> channel on FreeNode.</p>

doc/.templates/layout.html

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{% extends "!layout.html" %}
2+
3+
{% block rootrellink %}
4+
<li><a href="{{ pathto('index') }}">Sphinx home </a> |&nbsp;</li>
5+
<li><a href="{{ pathto('contents') }}">Documentation </a> &raquo;</li>
6+
{% endblock %}
7+
8+
{% block beforerelbar %}
9+
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
10+
<img src="{{ pathto("static/sphinx.png", 1) }}">
11+
</div>
12+
{% endblock %}

doc/builders.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.. _builders:
2+
3+
Builders and the environment
4+
============================
5+
6+
.. module:: sphinx.builder
7+
:synopsis: Available built-in builder classes.
8+
9+

doc/concepts.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.. _concepts:
2+
3+
Sphinx concepts
4+
===============
5+
6+
7+
The TOC tree
8+
------------
9+
10+
11+
Document names
12+
--------------
13+
14+

doc/conf.py

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# Sphinx documentation build configuration file, created by
4+
# sphinx-quickstart.py on Sat Mar 8 21:47:50 2008.
5+
#
6+
# This file is execfile()d with the current directory set to its containing dir.
7+
#
8+
# The contents of this file are pickled, so don't put values in the namespace
9+
# that aren't pickleable (module imports are okay, they're removed automatically).
10+
#
11+
# All configuration values have a default value; values that are commented out
12+
# serve to show the default value.
13+
14+
import sys
15+
16+
# If your extensions are in another directory, add it here.
17+
sys.path.append('.')
18+
19+
# General configuration
20+
# ---------------------
21+
22+
# Add any Sphinx extension module names here, as strings. They can be extensions
23+
# coming with Sphinx (named 'sphinx.addons.*') or your custom ones.
24+
extensions = ['ext']
25+
26+
# Add any paths that contain templates here, relative to this directory.
27+
templates_path = ['.templates']
28+
29+
# The suffix of source filenames.
30+
source_suffix = '.rst'
31+
32+
# The master toctree document.
33+
master_doc = 'contents'
34+
35+
# General substitutions.
36+
project = 'Sphinx'
37+
copyright = '2008, Georg Brandl'
38+
39+
# The default replacements for |version| and |release|, also used in various
40+
# other places throughout the built documents.
41+
#
42+
# The short X.Y version.
43+
version = '0.1'
44+
# The full version, including alpha/beta/rc tags.
45+
release = '0.1'
46+
47+
# There are two options for replacing |today|: either, you set today to some
48+
# non-false value, then it is used:
49+
#today = ''
50+
# Else, today_fmt is used as the format for a strftime call.
51+
today_fmt = '%B %d, %Y'
52+
53+
# List of documents that shouldn't be included in the build.
54+
#unused_docs = []
55+
56+
# If true, '()' will be appended to :func: etc. cross-reference text.
57+
#add_function_parentheses = True
58+
59+
# If true, the current module name will be prepended to all description
60+
# unit titles (such as .. function::).
61+
#add_module_names = True
62+
63+
show_authors = True
64+
65+
# The name of the Pygments (syntax highlighting) style to use.
66+
pygments_style = 'friendly'
67+
68+
69+
# Options for HTML output
70+
# -----------------------
71+
72+
# The style sheet to use for HTML and HTML Help pages. A file of that name
73+
# must exist either in Sphinx' static/ path, or in one of the custom paths
74+
# given in html_static_path.
75+
html_style = 'sphinxdoc.css'
76+
77+
# Add any paths that contain custom static files (such as style sheets) here,
78+
# relative to this directory. They are copied after the builtin static files,
79+
# so a file named "default.css" will overwrite the builtin "default.css".
80+
html_static_path = ['.static']
81+
82+
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
83+
# using the given strftime format.
84+
html_last_updated_fmt = '%b %d, %Y'
85+
86+
# If true, SmartyPants will be used to convert quotes and dashes to
87+
# typographically correct entities.
88+
#html_use_smartypants = True
89+
90+
# Content template for the index page.
91+
html_index = 'index.html'
92+
93+
# Custom sidebar templates, maps page names to templates.
94+
html_sidebars = {'index': 'indexsidebar.html'}
95+
96+
# Additional templates that should be rendered to pages, maps page names to
97+
# templates.
98+
#html_additional_pages = {}
99+
100+
# If true, the reST sources are included in the HTML build as _sources/<name>.
101+
#html_copy_source = True
102+
103+
# Output file base name for HTML help builder.
104+
htmlhelp_basename = 'Sphinxdoc'
105+
106+
107+
# Options for LaTeX output
108+
# ------------------------
109+
110+
# The paper size ('letter' or 'a4').
111+
#latex_paper_size = 'letter'
112+
113+
# The font size ('10pt', '11pt' or '12pt').
114+
#latex_font_size = '10pt'
115+
116+
# Grouping the document tree into LaTeX files. List of tuples
117+
# (source start file, target name, title, author, document class [howto/manual]).
118+
latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
119+
'Georg Brandl', 'manual')]
120+
121+
# Additional stuff for the LaTeX preamble.
122+
#latex_preamble = ''
123+
124+
# Documents to append as an appendix to all manuals.
125+
#latex_appendices = []

0 commit comments

Comments
 (0)