diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index ebe38178..00000000 --- a/doc/Makefile +++ /dev/null @@ -1,105 +0,0 @@ -# Copyright (c) 2010 OpenStack, LLC. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or -# implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build -export PYTHONPATH = ../ - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Swift.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Swift.qhc" - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ - "run these through (pdf)latex." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/source/conf.py b/doc/source/conf.py index 3baffd3d..b72990c1 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -31,13 +31,14 @@ import sys, os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.append(os.path.abspath('.')) +sys.path.append([os.path.abspath('../swift'), os.path.abspath('..'), os.path.abspath('../bin')]) # -- General configuration ----------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig'] +todo_include_todos = True # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -93,13 +94,13 @@ exclude_trees = [] # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False +show_authors = True # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +modindex_common_prefix = ['swift.'] # -- Options for HTML output --------------------------------------------------- @@ -173,7 +174,7 @@ html_static_path = ['_static'] #html_file_suffix = '' # Output file base name for HTML help builder. -htmlhelp_basename = 'Swiftdoc' +htmlhelp_basename = 'swiftdoc' # -- Options for LaTeX output -------------------------------------------------- @@ -207,3 +208,8 @@ latex_documents = [ # If false, no module index is generated. #latex_use_modindex = True + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'python': ('http://docs.python.org/', None), + 'nova': ('http://nova.openstack.org', None)} + diff --git a/swift/account/server.py b/swift/account/server.py index 9654670c..211013fd 100644 --- a/swift/account/server.py +++ b/swift/account/server.py @@ -114,7 +114,7 @@ class AccountController(object): def HEAD(self, req): """Handle HTTP HEAD request.""" - # TODO: Refactor: The account server used to provide a 'account and + # TODO(refactor): The account server used to provide a 'account and # container existence check all-in-one' call by doing a HEAD with a # container path. However, container existence is now checked with the # container servers directly so this is no longer needed. We should diff --git a/swift/common/client.py b/swift/common/client.py index 3f3b9d8b..e900c682 100644 --- a/swift/common/client.py +++ b/swift/common/client.py @@ -664,9 +664,9 @@ class Connection(object): def get_account(self, marker=None, limit=None, prefix=None, full_listing=False): """Wrapper for get_account""" - # TODO: With full_listing=True this will restart the entire listing - # with each retry. Need to make a better version that just retries - # where it left off. + # TODO(unknown): With full_listing=True this will restart the entire + # listing with each retry. Need to make a better version that just + # retries where it left off. return self._retry(get_account, marker=marker, limit=limit, prefix=prefix, full_listing=full_listing) @@ -677,9 +677,9 @@ class Connection(object): def get_container(self, container, marker=None, limit=None, prefix=None, delimiter=None, full_listing=False): """Wrapper for get_container""" - # TODO: With full_listing=True this will restart the entire listing - # with each retry. Need to make a better version that just retries - # where it left off. + # TODO(unknown): With full_listing=True this will restart the entire + # listing with each retry. Need to make a better version that just + # retries where it left off. return self._retry(get_container, container, marker=marker, limit=limit, prefix=prefix, delimiter=delimiter, full_listing=full_listing) diff --git a/swift/common/db_replicator.py b/swift/common/db_replicator.py index b8df3303..4efdc96e 100644 --- a/swift/common/db_replicator.py +++ b/swift/common/db_replicator.py @@ -435,7 +435,7 @@ class Replicator(object): class ReplicatorRpc(object): - """Handle Replication RPC calls. TODO: redbo document please :)""" + """Handle Replication RPC calls. TODO(redbo): document please :)""" def __init__(self, root, datadir, broker_class, mount_check=True): self.root = root @@ -472,7 +472,7 @@ class ReplicatorRpc(object): info = broker.get_replication_info() except Exception, e: if 'no such table' in str(e): - # TODO find a real logger + # TODO(unknown): find a real logger print "Quarantining DB %s" % broker.db_file quarantine_db(broker.db_file, broker.db_type) return HTTPNotFound()