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

…EADME.rst

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)
 ==================
 

docs/.gitignore

@@ -0,0 +1 @@
+_build/

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."
+

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
 

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.

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

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]

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 = """\