Skip to content
Browse files

fix docs rendering, add docs alias to setup.cfg, move README.txt to R…

…EADME.rst
  • Loading branch information...
1 parent a3ecea6 commit 6d2acbe1a56981ce311b45a803ee9f236a8fda78 @mcdonc mcdonc committed Apr 15, 2012
Showing with 81 additions and 38 deletions.
  1. +7 −0 CHANGES.txt
  2. 0 README.txt → README.rst
  3. +1 −0 docs/.gitignore
  4. +37 −21 docs/Makefile
  5. +14 −11 docs/conf.py
  6. +12 −0 docs/glossary.rst
  7. +5 −3 docs/usage.rst
  8. +1 −0 setup.cfg
  9. +4 −3 setup.py
View
7 CHANGES.txt
@@ -1,3 +1,10 @@
+Next release
+============
+
+- Fix docs rendering.
+
+- Add "dev" and "docs" aliases to setup.cfg.
+
0.8.1 (2011-08-17)
==================
View
0 README.txt → README.rst
File renamed without changes.
View
1 docs/.gitignore
@@ -0,0 +1 @@
+_build/
View
58 docs/Makefile
@@ -2,14 +2,14 @@
#
# You can set these variables from the command line.
-SPHINXOPTS =
+SPHINXOPTS = -W
SPHINXBUILD = sphinx-build
PAPER =
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d .build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html web pickle htmlhelp latex changes linkcheck
@@ -23,48 +23,64 @@ help:
@echo " linkcheck to check all external links for integrity"
clean:
- -rm -rf .build/*
+ -rm -rf _build/*
html:
- mkdir -p .build/html .build/doctrees
- $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) .build/html
+ mkdir -p _build/html _build/doctrees
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
@echo
- @echo "Build finished. The HTML pages are in .build/html."
+ @echo "Build finished. The HTML pages are in _build/html."
+
+text:
+ mkdir -p _build/text _build/doctrees
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text
+ @echo
+ @echo "Build finished. The HTML pages are in _build/text."
pickle:
- mkdir -p .build/pickle .build/doctrees
- $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) .build/pickle
+ mkdir -p _build/pickle _build/doctrees
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
@echo
@echo "Build finished; now you can process the pickle files or run"
- @echo " sphinx-web .build/pickle"
+ @echo " sphinx-web _build/pickle"
@echo "to start the sphinx-web server."
web: pickle
htmlhelp:
- mkdir -p .build/htmlhelp .build/doctrees
- $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) .build/htmlhelp
+ mkdir -p _build/htmlhelp _build/doctrees
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
- ".hhp project file in .build/htmlhelp."
+ ".hhp project file in _build/htmlhelp."
latex:
- mkdir -p .build/latex .build/doctrees
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) .build/latex
+ mkdir -p _build/latex _build/doctrees
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
+ cp _static/*.png _build/latex
+ ./convert_images.sh
+ cp _static/latex-warning.png _build/latex
+ cp _static/latex-note.png _build/latex
@echo
- @echo "Build finished; the LaTeX files are in .build/latex."
+ @echo "Build finished; the LaTeX files are in _build/latex."
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
"run these through (pdf)latex."
changes:
- mkdir -p .build/changes .build/doctrees
- $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) .build/changes
+ mkdir -p _build/changes _build/doctrees
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
@echo
- @echo "The overview file is in .build/changes."
+ @echo "The overview file is in _build/changes."
linkcheck:
- mkdir -p .build/linkcheck .build/doctrees
- $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) .build/linkcheck
+ mkdir -p _build/linkcheck _build/doctrees
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
- "or in .build/linkcheck/output.txt."
+ "or in _build/linkcheck/output.txt."
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) _build/epub
+ @echo
+ @echo "Build finished. The epub file is in _build/epub."
+
View
25 docs/conf.py
@@ -15,16 +15,19 @@
# If your extensions are in another directory, add it here. If the directory
# is relative to the documentation root, use os.path.abspath to make it
# absolute, like shown here.
-parent = os.path.dirname(os.path.dirname(__file__))
-sys.path.append(os.path.abspath(parent))
-wd = os.getcwd()
-os.chdir(parent)
-os.system('%s setup.py test -q' % sys.executable)
-os.chdir(wd)
-for item in os.listdir(parent):
- if item.endswith('.egg'):
- sys.path.append(os.path.join(parent, item))
+if 'sphinx-build' in ' '.join(sys.argv): # protect against dumb importers
+ parent = os.path.dirname(os.path.dirname(__file__))
+ sys.path.append(os.path.abspath(parent))
+ wd = os.getcwd()
+ os.chdir(parent)
+ os.system('%s setup.py test -q' % sys.executable)
+ os.chdir(wd)
+
+ for item in os.listdir(parent):
+ if item.endswith('.egg'):
+ sys.path.append(os.path.join(parent, item))
+
# General configuration
# ---------------------
@@ -44,13 +47,13 @@
# General substitutions.
project = 'repoze.catalog'
-copyright = '2008-2011, Agendaless Consulting'
+copyright = '2008-2012, Agendaless Consulting'
# The default replacements for |version| and |release|, also used in various
# other places throughout the built documents.
#
# The short X.Y version.
-version = '0.8.0'
+version = '0.8.1'
# The full version, including alpha/beta/rc tags.
release = version
View
12 docs/glossary.rst
@@ -10,48 +10,60 @@ Glossary
`Setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_
builds on Python's ``distutils`` to provide easier building,
distribution, and installation of packages.
+
Interface
An attribute of a model object that determines its type. It is an
instance of a ``zope.interface`` Interface class.
+
Zope
`The Z Object Publishing Framework <http://zope.org>`_. The granddaddy
of Python web frameworks.
+
ZODB
`The Zope Object Database <http://wiki.zope.org/ZODB/FrontPage>`_
which is a persistent object store for Python.
+
Field index
A type of index that is optimized to index single simple tokenized
values. When a field index is searched, it can be searched for
one or more values, and it will return a result set that includes
these values exacty.
+
Text index
A type of index which indexes a value in such a way that parts of
it can be searched in a non-exact manner. When a text index is
searched, it returns results for values that match based on
various properties of the text indexed, such as omitting
"stopwords" the text might have.
+
Facet index
A type of index which can be used for faceted search.
+
Path index
A type of index that keeps track of documents within a graph;
documents can be searched for by their position in the graph.
+
zope.index
The `underlying indexing machinery
<http://pypi.python.org/pypi/zope.index>`_ that
:mod:`repoze.catalog` uses.
+
zope.app.catalog
The `cataloging implementation
<http://pypi.python.org/pypi/zope.app.catalog>`_ on which
:mod:`repoze.catalog` is based (although it doesn't use any of
its code).
+
Virtualenv
An isolated Python environment. Allows you to control which
packages are used on a particular project by cloning your main
Python. `virtualenv <http://pypi.python.org/pypi/virtualenv>`_
was created by Ian Bicking.
+
CQE
A string representing a Python-like domain-specific-language
expression which is used to generate a query object.
+
Query Object
An object used as an argument to the :meth:`repoze.catalog.Catalog.query`
method's ``queryobject`` parameter.
View
8 docs/usage.rst
@@ -498,9 +498,11 @@ CQE::
Search Using the :meth:`repoze.catalog.Catalog.search` Method (Deprecated)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. warning:: The :meth:`repoze.catalog.Catalog.search` method is
- deprecated as of :mod:`repoze.catalog` 0.8. Use
- :meth:`repoze.catalog.Catalog.query` instead.
+.. warning::
+
+ The :meth:`repoze.catalog.Catalog.search` method is deprecated as of
+ :mod:`repoze.catalog` 0.8. Use :meth:`repoze.catalog.Catalog.query`
+ instead.
We can pass a query into our catalog's ``search`` method, which is
composed of the name of our index and a value we'd like to find a
View
1 setup.cfg
@@ -7,3 +7,4 @@ cover-package=repoze.catalog
[aliases]
dev = develop easy_install repoze.catalog[testing]
+docs = develop easy_install repoze.catalog[docs]
View
7 setup.py
@@ -15,20 +15,20 @@
__version__ = '0.8.1'
import os
-import sys
from setuptools import setup, find_packages
try:
here = os.path.abspath(os.path.dirname(__file__))
- README = open(os.path.join(here, 'README.txt')).read()
+ README = open(os.path.join(here, 'README.rst')).read()
CHANGES = open(os.path.join(here, 'CHANGES.txt')).read()
except IOError:
README = CHANGES = ''
install_requires = ['setuptools', 'zope.component', 'zope.index >= 3.5.0']
-testing_extras = install_requires + ['nose', 'coverage']
+testing_extras = ['nose', 'coverage']
+docs_extras = ['Sphinx']
setup(name='repoze.catalog',
version=__version__,
@@ -56,6 +56,7 @@
extras_require = {
'benchmark': ['PyChart'],
'testing': testing_extras,
+ 'docs':docs_extras,
},
test_suite="repoze.catalog",
## entry_points = """\

0 comments on commit 6d2acbe

Please sign in to comment.
Something went wrong with that request. Please try again.