diff --git a/.gitignore b/.gitignore index e191be82..95ad521c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ *.pyc .*.swp docs/.build +docs/_build diff --git a/docs/Makefile b/docs/Makefile index 66cd648f..76eb910c 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,7 +5,7 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = -BUILDDIR = .build +BUILDDIR = _build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 diff --git a/docs/.themes/nature/static/nature.css_t b/docs/_themes/nature/static/nature.css_t similarity index 100% rename from docs/.themes/nature/static/nature.css_t rename to docs/_themes/nature/static/nature.css_t diff --git a/docs/.themes/nature/static/pygments.css b/docs/_themes/nature/static/pygments.css similarity index 100% rename from docs/.themes/nature/static/pygments.css rename to docs/_themes/nature/static/pygments.css diff --git a/docs/.themes/nature/theme.conf b/docs/_themes/nature/theme.conf similarity index 100% rename from docs/.themes/nature/theme.conf rename to docs/_themes/nature/theme.conf diff --git a/docs/apireference.rst b/docs/apireference.rst new file mode 100644 index 00000000..9ec4321a --- /dev/null +++ b/docs/apireference.rst @@ -0,0 +1,46 @@ +API Reference +============= + +Connecting +---------- + +.. autofunction:: mongoengine.connect + +Documents +--------- + +.. autoclass:: mongoengine.Document + :members: + + .. attribute:: objects + + A :class:`~mongoengine.queryset.QuerySet` object that is created lazily + on access. + +.. autoclass:: mongoengine.EmbeddedDocument + :members: + +Querying +-------- + +.. autoclass:: mongoengine.queryset.QuerySet + :members: + +Fields +------ + +.. autoclass:: mongoengine.StringField + +.. autoclass:: mongoengine.IntField + +.. autoclass:: mongoengine.FloatField + +.. autoclass:: mongoengine.DateTimeField + +.. autoclass:: mongoengine.EmbeddedDocumentField + +.. autoclass:: mongoengine.ListField + +.. autoclass:: mongoengine.ObjectIdField + +.. autoclass:: mongoengine.ReferenceField diff --git a/docs/conf.py b/docs/conf.py index 5b29b371..be7d3f5d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,13 +16,13 @@ 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('..')) # -- 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 = [] +extensions = ['sphinx.ext.autodoc'] # Add any paths that contain templates here, relative to this directory. templates_path = ['.templates'] @@ -64,7 +64,7 @@ release = '0.1' # List of directories, relative to source directory, that shouldn't be searched # for source files. -exclude_trees = ['.build'] +exclude_trees = ['_build'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None @@ -99,7 +99,7 @@ html_theme = 'nature' #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -html_theme_path = ['.themes'] +html_theme_path = ['_themes'] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -120,7 +120,7 @@ html_theme_path = ['.themes'] # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['.static'] +html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/docs/index.rst b/docs/index.rst index 5fab07a6..e6a2bde6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,7 +3,7 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to MongoEngine's documentation! +MongoEngine User Documentation ======================================= Contents: @@ -12,6 +12,7 @@ Contents: :maxdepth: 2 tutorial.rst + apireference.rst Indices and tables ================== diff --git a/mongoengine/document.py b/mongoengine/document.py index 99c98cd4..a4b78619 100644 --- a/mongoengine/document.py +++ b/mongoengine/document.py @@ -6,32 +6,58 @@ __all__ = ['Document', 'EmbeddedDocument'] class EmbeddedDocument(BaseDocument): + """A :class:`~mongoengine.Document` that isn't stored in its own + collection. :class:`~mongoengine.EmbeddedDocument`\ s should be used as + fields on :class:`~mongoengine.Document`\ s through the + :class:`~mongoengine.EmbeddedDocumentField` field type. + """ __metaclass__ = DocumentMetaclass class Document(BaseDocument): + """The base class used for defining the structure and properties of + collections of documents stored in MongoDB. Inherit from this class, and + add fields as class attributes to define a document's structure. + Individual documents may then be created by making instances of the + :class:`~mongoengine.Document` subclass. + + By default, the MongoDB collection used to store documents created using a + :class:`~mongoengine.Document` subclass will be the name of the subclass + converted to lowercase. A different collection may be specified by + providing :attr:`collection` to the :attr:`meta` dictionary in the class + definition. + + A :class:`~mongoengine.Document` subclass may be itself subclassed, to + create a specialised version of the document that will be stored in the + same collection. To facilitate this behaviour, `_cls` and `_types` + fields are added to documents (hidden though the MongoEngine interface + though). To disable this behaviour and remove the dependence on the + presence of `_cls` and `_types`, set :attr:`allow_inheritance` to + ``False`` in the :attr:`meta` dictionary. + """ __metaclass__ = TopLevelDocumentMetaclass def save(self): - """Save the document to the database. If the document already exists, - it will be updated, otherwise it will be created. + """Save the :class:`~mongoengine.Document` to the database. If the + document already exists, it will be updated, otherwise it will be + created. """ object_id = self.objects._collection.save(self.to_mongo()) self.id = object_id def delete(self): - """Delete the document from the database. This will only take effect - if the document has been previously saved. + """Delete the :class:`~mongoengine.Document` from the database. This + will only take effect if the document has been previously saved. """ object_id = self._fields['id'].to_mongo(self.id) self.__class__.objects(_id=object_id).delete() @classmethod def drop_collection(cls): - """Drops the entire collection associated with this Document type from - the database. + """Drops the entire collection associated with this + :class:`~mongoengine.Document` type from the database. """ db = _get_db() db.drop_collection(cls._meta['collection']) diff --git a/mongoengine/fields.py b/mongoengine/fields.py index 1625a582..e97aadb2 100644 --- a/mongoengine/fields.py +++ b/mongoengine/fields.py @@ -87,7 +87,7 @@ class DateTimeField(BaseField): class EmbeddedDocumentField(BaseField): """An embedded document field. Only valid values are subclasses of - EmbeddedDocument. + :class:`~mongoengine.EmbeddedDocument`. """ def __init__(self, document, **kwargs): diff --git a/mongoengine/queryset.py b/mongoengine/queryset.py index 4f406b44..3678b099 100644 --- a/mongoengine/queryset.py +++ b/mongoengine/queryset.py @@ -5,7 +5,7 @@ import pymongo class QuerySet(object): """A set of results returned from a query. Wraps a MongoDB cursor, - providing Document objects as the results. + providing :class:`~mongoengine.Document` objects as the results. """ def __init__(self, document, collection): @@ -32,7 +32,8 @@ class QuerySet(object): return self def __call__(self, **query): - """Filter the selected documents by calling the queryset with a query. + """Filter the selected documents by calling the + :class:`~mongoengine.QuerySet` with a query. """ self._query.update(QuerySet._transform_query(**query)) return self @@ -76,7 +77,7 @@ class QuerySet(object): return result def with_id(self, object_id): - """Retrieve the object matching the _id provided. + """Retrieve the object matching the id provided. """ if not isinstance(object_id, pymongo.objectid.ObjectId): object_id = pymongo.objectid.ObjectId(object_id) @@ -87,7 +88,7 @@ class QuerySet(object): return result def next(self): - """Wrap the result in a Document object. + """Wrap the result in a :class:`~mongoengine.Document` object. """ return self._document._from_son(self._cursor.next()) @@ -97,21 +98,22 @@ class QuerySet(object): return self._cursor.count() def limit(self, n): - """Limit the number of returned documents to. + """Limit the number of returned documents to `n`. """ self._cursor.limit(n) # Return self to allow chaining return self def skip(self, n): - """Skip n documents before returning the results. + """Skip `n` documents before returning the results. """ self._cursor.skip(n) return self def order_by(self, *keys): - """Order the QuerySet by the keys. The order may be specified by - prepending each of the keys by a + or a -. Ascending order is assumed. + """Order the :class:`~mongoengine.queryset.QuerySet` by the keys. The + order may be specified by prepending each of the keys by a + or a -. + Ascending order is assumed. """ key_list = [] for key in keys: @@ -126,6 +128,9 @@ class QuerySet(object): return self def explain(self, format=False): + """Return an explain plan record for the + :class:`~mongoengine.queryset.QuerySet`\ 's cursor. + """ plan = self._cursor.explain() if format: import pprint