Skip to content

Commit ca1fc96

Browse files
author
James William Pye
committed
Add sphinx build management directory.
1 parent 78c834e commit ca1fc96

3 files changed

Lines changed: 307 additions & 0 deletions

File tree

‎sphinx-src/Makefile‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# You can set these variables from the command line.
2+
SPHINXOPTS =
3+
SPHINXBUILD = sphinx-build
4+
PAPER =
5+
BUILD_DIR = ../sphinx
6+
7+
# Internal variables.
8+
PAPEROPT_a4 = -D latex_paper_size=a4
9+
PAPEROPT_letter = -D latex_paper_size=letter
10+
ALLSPHINXOPTS = -d $(BUILD_DIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
11+
12+
.PHONY: help clean dump html web pickle htmlhelp latex changes linkcheck
13+
14+
help:
15+
@echo "Please use \`make <target>' where <target> is one of"
16+
@echo " html to make standalone HTML files"
17+
@echo " pickle to make pickle files (usable by e.g. sphinx-web)"
18+
@echo " htmlhelp to make HTML files and a HTML help project"
19+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
20+
@echo " changes to make an overview over all changed/added/deprecated items"
21+
@echo " linkcheck to check all external links for integrity"
22+
23+
clean:
24+
-rm -rf *.txt
25+
-rm -rf ../sphinx
26+
-rm -f meta.py*
27+
28+
html: dump
29+
mkdir -p $(BUILD_DIR) $(BUILD_DIR)/doctrees
30+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILD_DIR)
31+
@echo
32+
@echo "Build finished. The HTML pages are in $(BUILD_DIR)."
33+
34+
pickle: dump
35+
mkdir -p $(BUILD_DIR)/pickle $(BUILD_DIR)/doctrees
36+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILD_DIR)/pickle
37+
@echo
38+
@echo "Build finished; now you can process the pickle files or run"
39+
@echo " sphinx-web $(BUILD_DIR)/pickle"
40+
@echo "to start the sphinx-web server."
41+
42+
web: pickle
43+
44+
htmlhelp: dump
45+
mkdir -p $(BUILD_DIR)/htmlhelp $(BUILD_DIR)/doctrees
46+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILD_DIR)/htmlhelp
47+
@echo
48+
@echo "Build finished; now you can run HTML Help Workshop with the" \
49+
".hhp project file in $(BUILD_DIR)/htmlhelp."
50+
51+
latex: dump
52+
mkdir -p $(BUILD_DIR)/latex $(BUILD_DIR)/doctrees
53+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILD_DIR)/latex
54+
@echo
55+
@echo "Build finished; the LaTeX files are in $(BUILD_DIR)/latex."
56+
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
57+
"run these through (pdf)latex."
58+
59+
changes: dump
60+
mkdir -p $(BUILD_DIR)/changes $(BUILD_DIR)/doctrees
61+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILD_DIR)/changes
62+
@echo
63+
@echo "The overview file is in $(BUILD_DIR)/changes."
64+
65+
linkcheck: dump
66+
mkdir -p $(BUILD_DIR)/linkcheck $(BUILD_DIR)/doctrees
67+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILD_DIR)/linkcheck
68+
@echo
69+
@echo "Link check complete; look for any errors in the above output " \
70+
"or in $(BUILD_DIR)/linkcheck/output.txt."
71+
72+
dump:
73+
cp ../postgresql/__init__.py ./meta.py
74+
cp index.rst index.txt
75+
env PYTHONPATH=.. python -m postgresql.documentation.driver dump >driver.txt
76+
env PYTHONPATH=.. python -m postgresql.documentation.admin dump >admin.txt
77+
env PYTHONPATH=.. python -m postgresql.documentation.gotchas dump >gotchas.txt

‎sphinx-src/conf.py‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# py-postgresql documentation build configuration file, created by
4+
# sphinx-quickstart on Mon Mar 2 17:21:37 2009.
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, os
15+
sys.path.insert(0, '.')
16+
17+
# If your extensions are in another directory, add it here. If the directory
18+
# is relative to the documentation root, use os.path.abspath to make it
19+
# absolute, like shown here.
20+
#sys.path.append(os.path.abspath('some/directory'))
21+
22+
# General configuration
23+
# ---------------------
24+
25+
# Add any Sphinx extension module names here, as strings. They can be extensions
26+
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
27+
extensions = []
28+
29+
# Add any paths that contain templates here, relative to this directory.
30+
templates_path = ['.templates']
31+
32+
# The suffix of source filenames.
33+
source_suffix = '.txt'
34+
35+
# The master toctree document.
36+
master_doc = 'index'
37+
38+
# General substitutions.
39+
import meta
40+
project = meta.__project__
41+
copyright = meta.__date__ + ', ' + meta.__author__
42+
43+
# The default replacements for |version| and |release|, also used in various
44+
# other places throughout the built documents.
45+
#
46+
# The short X.Y version.
47+
version = meta.__version__
48+
# The full version, including alpha/beta/rc tags.
49+
release = '.'.join([str(x) for x in meta.version_info[:-2]]) + ''.join([str(x) for x in meta.version_info[-2:]])
50+
51+
# There are two options for replacing |today|: either, you set today to some
52+
# non-false value, then it is used:
53+
#today = ''
54+
# Else, today_fmt is used as the format for a strftime call.
55+
today_fmt = '%B %d, %Y'
56+
57+
# List of documents that shouldn't be included in the build.
58+
#unused_docs = []
59+
60+
# List of directories, relative to source directories, that shouldn't be searched
61+
# for source files.
62+
#exclude_dirs = []
63+
64+
# The reST default role (used for this markup: `text`) to use for all documents.
65+
#default_role = None
66+
67+
# If true, '()' will be appended to :func: etc. cross-reference text.
68+
#add_function_parentheses = True
69+
70+
# If true, the current module name will be prepended to all description
71+
# unit titles (such as .. function::).
72+
#add_module_names = True
73+
74+
# If true, sectionauthor and moduleauthor directives will be shown in the
75+
# output. They are ignored by default.
76+
#show_authors = False
77+
78+
# The name of the Pygments (syntax highlighting) style to use.
79+
pygments_style = 'sphinx'
80+
81+
82+
# Options for HTML output
83+
# -----------------------
84+
85+
# The style sheet to use for HTML and HTML Help pages. A file of that name
86+
# must exist either in Sphinx' static/ path, or in one of the custom paths
87+
# given in html_static_path.
88+
html_style = 'default.css'
89+
90+
# The name for this set of Sphinx documents. If None, it defaults to
91+
# "<project> v<release> documentation".
92+
#html_title = None
93+
94+
# A shorter title for the navigation bar. Default is the same as html_title.
95+
#html_short_title = None
96+
97+
# The name of an image file (within the static path) to place at the top of
98+
# the sidebar.
99+
#html_logo = None
100+
101+
# The name of an image file (within the static path) to use as favicon of the
102+
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
103+
# pixels large.
104+
#html_favicon = None
105+
106+
# Add any paths that contain custom static files (such as style sheets) here,
107+
# relative to this directory. They are copied after the builtin static files,
108+
# so a file named "default.css" will overwrite the builtin "default.css".
109+
html_static_path = ['.static']
110+
111+
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
112+
# using the given strftime format.
113+
html_last_updated_fmt = '%b %d, %Y'
114+
115+
# If true, SmartyPants will be used to convert quotes and dashes to
116+
# typographically correct entities.
117+
#html_use_smartypants = True
118+
119+
# Custom sidebar templates, maps document names to template names.
120+
#html_sidebars = {}
121+
122+
# Additional templates that should be rendered to pages, maps page names to
123+
# template names.
124+
#html_additional_pages = {}
125+
126+
# If false, no module index is generated.
127+
#html_use_modindex = True
128+
129+
# If false, no index is generated.
130+
#html_use_index = True
131+
132+
# If true, the index is split into individual pages for each letter.
133+
#html_split_index = False
134+
135+
# If true, the reST sources are included in the HTML build as _sources/<name>.
136+
#html_copy_source = True
137+
138+
# If true, an OpenSearch description file will be output, and all pages will
139+
# contain a <link> tag referring to it. The value of this option must be the
140+
# base URL from which the finished HTML is served.
141+
#html_use_opensearch = ''
142+
143+
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
144+
#html_file_suffix = ''
145+
146+
# Output file base name for HTML help builder.
147+
htmlhelp_basename = meta.__project__
148+
149+
150+
# Options for LaTeX output
151+
# ------------------------
152+
153+
# The paper size ('letter' or 'a4').
154+
#latex_paper_size = 'letter'
155+
156+
# The font size ('10pt', '11pt' or '12pt').
157+
#latex_font_size = '10pt'
158+
159+
# Grouping the document tree into LaTeX files. List of tuples
160+
# (source start file, target name, title, author, document class [howto/manual]).
161+
latex_documents = [
162+
('index', 'py-postgresql.tex', 'py-postgresql documentation',
163+
'James William Pye', 'manual'),
164+
]
165+
166+
# The name of an image file (relative to this directory) to place at the top of
167+
# the title page.
168+
#latex_logo = None
169+
170+
# For "manual" documents, if this is true, then toplevel headings are parts,
171+
# not chapters.
172+
#latex_use_parts = False
173+
174+
# Additional stuff for the LaTeX preamble.
175+
#latex_preamble = ''
176+
177+
# Documents to append as an appendix to all manuals.
178+
#latex_appendices = []
179+
180+
# If false, no module index is generated.
181+
#latex_use_modindex = True

‎sphinx-src/index.rst‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
=============
2+
py-postgresql
3+
=============
4+
5+
py-postgresql is a project dedicated to improving Python interfaces to
6+
PostgreSQL. At its core, py-postgresql provides a PG-API and DB-API 2.0
7+
interfaces for accessing a PostgreSQL database.
8+
9+
.. toctree::
10+
:maxdepth: 3
11+
12+
admin
13+
driver
14+
gotchas
15+
16+
--------
17+
Examples
18+
--------
19+
20+
Sample PG-API code::
21+
22+
import postgresql.driver as pg_driver
23+
db = pg_driver.connect(
24+
user = 'usename', password = 'secret', host = 'localhost', port = 5432
25+
)
26+
db.execute("CREATE TABLE emp (emp_name text PRIMARY KEY, emp_salary numeric)")
27+
28+
# Create the statements.
29+
make_emp = db.prepare("INSERT INTO emp VALUES ($1, $2)")
30+
raise_emp = db.prepare("UPDATE emp SET emp_salary = emp_salary + $2 WHERE emp_name = $1")
31+
get_emp_salary = db.prepare("SELECT emp_salary FROM emp WHERE emp_name = $1")
32+
get_emp_with_salary_lt = db.prepare("SELECT emp_name FROM emp WHERE emp_salay < $1")
33+
34+
# Create some employees, but do it in a transaction--all or nothing.
35+
with db.xact:
36+
make_emp("John Doe", "150,000")
37+
make_emp("Jane Doe", "150,000")
38+
make_emp("Andrew Doe", "55,000")
39+
make_emp("Susan Doe", "60,000")
40+
41+
# Give some raises
42+
with db.xact:
43+
for row in get_emp_with_salary_lt("125,000"):
44+
print(row["emp_name"])
45+
raise_emp(row["emp_name"], "10,000")
46+
47+
48+
Of course, if DB-API 2.0 is desired, the module is located at
49+
`postgresql.driver.dbapi20`

0 commit comments

Comments
 (0)