diff --git a/.gitignore b/.gitignore deleted file mode 100644 index 2e79a6f4..00000000 --- a/.gitignore +++ /dev/null @@ -1,4 +0,0 @@ -.DS_Store -giza.log -build/ -.yardoc diff --git a/README.rst b/README.rst index d719f98c..d58e8179 100644 --- a/README.rst +++ b/README.rst @@ -1,135 +1,23 @@ -===================== -Mongoid Documentation -===================== +============================= +MongoDB Mongoid Documentation +============================= -This repository contains documentation for Mongoid, the object-document -mapper for MongoDB in Ruby. - -Build Locally -------------- - -To build the documentation locally, - -- Install `giza `_, if not already - installed. Note that giza requires Python 2.7 and does not work with Python 3. - There is an `installation guide - `_ on the MongoDB meta site - to help you get started. - -- Run the following to download and build this documentation locally:: - - git clone git@github.com:mongodb/docs-mongoid - cd docs-mongoid/ - make html - -The generated HTML will be placed in `build/master/html/`. - -*Note*: The build process invokes Sphinx and expects Sphinx's various -binaries to be in PATH. - -Stage ------ - -Install `mut `_ following its installation -instructions. Note that mut requires Python 3 and does not work with Python 2.7. - -Request access to the documentation staging bucket. Obtain AWS S3 -access key id and secret access key. - -Create ``~/.config/giza-aws-authentication.conf`` with the following contents:: - - [authentication] - accesskey= - secretkey= - -(If you run ``make stage`` without configuring authentication, it will -also give you these instructions.) - -Finally to publish the docs to the staging bucket, run:: - - make stage - -The output will include a URL to the published documentation. - -Deploy To Live Site -------------------- - -Install `mut `_ following its installation -instructions. Note that mut requires Python 3 and does not work with Python 2.7. - -Request access to the production documentation bucket. Obtain AWS S3 -access key id and secret access key. - -Create ``~/.config/giza-aws-authentication.conf`` with the following contents:: - - [authentication] - accesskey= - secretkey= - -Publish the docs to the production bucket:: - - make publish deploy - -Using Docker ------------- - -Build the docker image:: - - docker build -t docs-mongoid . - -Build the documentation to ``build`` subdir, clobbering its existing contents:: - - rm -rf build && \ - mkdir build && \ - docker run -itv `pwd`/build:/build \ - docs-mongoid sh -c 'make html && rsync -av build/ /build' - -Note that since Docker container runs everything as root, the built files -will also be owned by root and will require root access to modify or remove. - -Deploy to live site (no need to configure ``~/.config/giza-aws-authentication.conf`` -on the host system):: - - docker run -it \ - -e AWS_ACCESS_KEY_ID= \ - -e AWS_SECRET_ACCESS_KEY= \ - docs-mongoid make publish deploy - -Contribute ----------- - -To contribute to the documentation, please sign the `MongoDB -Contributor Agreement -`_ if you have not -already. - -See the following documents that provide an overview of the -documentation style and process: - -- `Style Guide `_ -- `Documentation Practices `_ -- `Documentation Organization `_ -- `Build Instructions `_ +This repository contains documentation for the MongoDB Mongoid ODM for Ruby. File JIRA Tickets ----------------- -File issue reports or requests at the `Documentation Jira Project -`_. - -Listed Mongoid Branches ------------------------ - -The branch list as well as which is the current one is maintained here: https://github.com/mongodb/docs-tools/blob/master/data/mongoid-published-branches.yaml +Please file issue reports or requests at the `Documentation Jira Project +`__. Licenses -------- All documentation is available under the terms of a `Creative Commons -License `_. +License `__. The MongoDB Documentation Project is governed by the terms of the `MongoDB Contributor Agreement -`_. +`__. -- The MongoDB Docs Team diff --git a/conf.py b/conf.py deleted file mode 100644 index 04b71b94..00000000 --- a/conf.py +++ /dev/null @@ -1,115 +0,0 @@ -# -*- coding: utf-8 -*- -# -# MongoDB documentation build configuration file, created by -# sphinx-quickstart on Mon Oct 3 09:58:40 2011. -# -# This file is execfile()d with the current directory set to its containing dir. - -import sys -import os.path -import datetime - -from sphinx.errors import SphinxError - -from giza.config.runtime import RuntimeStateConfig -from giza.config.helper import fetch_config, get_versions, get_manual_path - -conf = fetch_config(RuntimeStateConfig()) -sconf = conf.system.files.data.sphinx_local - -sys.path.append(os.path.join(conf.paths.projectroot, conf.paths.buildsystem, 'sphinxext')) - - -# -- General configuration ---------------------------------------------------- - -needs_sphinx = '1.0' - -extensions = [ - 'sphinx.ext.extlinks', - 'sphinx.ext.todo', - 'mongodb', - 'directives', - 'intermanual', - 'fasthtml' -] - -locale_dirs = [ os.path.join(conf.paths.projectroot, conf.paths.locale) ] -gettext_compact = False - -templates_path = ['.templates'] -exclude_patterns = [] - -source_suffix = '.txt' - -master_doc = sconf.master_doc -language = 'en' -project = sconf.project - -copyright = u'2008-{0}'.format(datetime.date.today().year) - -version = conf.version.branch -release = conf.version.release - - -rst_epilog = '\n'.join([ - '.. |branch| replace:: ``{0}``'.format(conf.git.branches.current), - '.. |copy| unicode:: U+000A9', - '.. |year| replace:: {0}'.format(datetime.date.today().year), - '.. |hardlink| replace:: http://docs.mongodb.com/mongoid', -]) - -pygments_style = 'sphinx' - -extlinks = { - 'manual': ('https://www.mongodb.com/docs/manual%s', ''), -} - -## add `extlinks` for each published version. -for i in conf.git.branches.published: - extlinks[i] = ( ''.join([ conf.project.url, '/', i, '%s' ]), '' ) - -intersphinx_mapping = {} - -intersphinx_mapping = {} -for i in conf.system.files.data.intersphinx: - intersphinx_mapping[i.name] = ( i.url, os.path.join(conf.paths.projectroot, - conf.paths.output, - i.path)) - -languages = [] -# -- Options for HTML output --------------------------------------------------- - -html_theme = sconf.theme.name -html_theme_path = [ os.path.join(conf.paths.buildsystem, 'themes') ] -html_title = conf.project.title -htmlhelp_basename = 'MongoDB' - -html_logo = ".static/logo-mongodb.png" - -html_copy_source = False -html_domain_indices = True -html_use_index = False -html_split_index = False -html_show_sourcelink = False -html_show_sphinx = True -html_show_copyright = True - - -html_theme_options = { - 'branch': conf.git.branches.current, - 'manual_path': get_manual_path(conf), - 'translations': languages, - 'language': language, - 'repo_name': sconf.theme.repo, - 'jira_project': sconf.theme.jira, - 'google_analytics': sconf.theme.google_analytics, - 'project': sconf.theme.project, - 'version': version, - 'version_selector': get_versions(conf), - 'active_branches': conf.version.active, - 'stable': conf.version.stable, - 'sitename': sconf.theme.sitename, - 'nav_excluded': sconf.theme.nav_excluded, -} - -html_sidebars = sconf.sidebars diff --git a/config/build_conf.yaml b/config/build_conf.yaml deleted file mode 100644 index c6673055..00000000 --- a/config/build_conf.yaml +++ /dev/null @@ -1,41 +0,0 @@ -git: - repo: 'mongodb/docs-mongoid' - remote: - upstream: 'mongodb/docs-mongoid' - tools: 'mongodb/docs-tools' -project: - name: 'mongoid' - tag: 'mongoid' - url: 'https://docs.mongodb.com/mongoid' - title: 'Mongoid Manual' - branched: true -version: - release: 'upcoming' - branch: 'master' -system: - runstate: - serial_sphinx: publish - files: - - 'intersphinx.yaml' - - 'integration.yaml' - - 'sphinx_local.yaml' - - 'push.yaml' - - htaccess: ['htaccess.yaml'] -assets: - - branch: master - path: build/docs-tools - repository: https://github.com/mongodb/docs-tools.git - - branch: master - path: build/mongoid-master - repository: https://github.com/mongodb/mongoid.git -paths: - output: 'build' - source: 'source-master' - includes: 'source-master/includes' - images: 'source-master/images' - tools: 'bin' - buildsystem: 'build/docs-tools' - builddata: 'config' - locale: 'locale' - -... \ No newline at end of file diff --git a/config/htaccess.yaml b/config/htaccess.yaml deleted file mode 100644 index b6cb9da8..00000000 --- a/config/htaccess.yaml +++ /dev/null @@ -1,31 +0,0 @@ -# Each YAML document has the following schema: -# -# from: "the path to the redirected URL" -# to: "the path to the new location for the resource" -# type: "currently this script only supports 'redirect', and -# ignores all documents with another type." -# code: "the HTTP redirect code. Raises exception if not 301, 302, 303." -# outputs: "a list of branches/paths as follows:" -# -# - 'all': generates redirects for all published branches, but *not* 'manual'. But giza will take care of manual as part of integration.yaml logic in redirects.py -# -# - '': generates redirects for a specific branch. -# -# - 'before-': generates redirects for all branches that -# reflect releases previous to the specified branch. (Inclusive.) -# -# - 'after-': generates redirects for all branches that -# reflect releases after the specified branch. (Non-inclusive.) -# -# All paths are relative to the ``source/`` directory. -# -######################################################################## -### Giza requires this file, even if no redirects -### More as a safety -- in case, we remove redirects during deploys -from: '/' -to: '/master' -type: 'redirect' -code: 301 -outputs: - - {'/mongoid': 'https://docs.mongodb.com/mongoid'} -... diff --git a/config/integration.yaml b/config/integration.yaml deleted file mode 100644 index 406866dd..00000000 --- a/config/integration.yaml +++ /dev/null @@ -1,10 +0,0 @@ -base: - links: - - { '6.2': 'master' } - targets: - - 'html' - - 'dirhtml' - doc-root: - - 'sitemap.xml' - - '.htaccess' - branch-root: [] diff --git a/config/push.yaml b/config/push.yaml deleted file mode 100644 index a3795069..00000000 --- a/config/push.yaml +++ /dev/null @@ -1,2 +0,0 @@ -### Apparently, giza requires this file, even if empty -### Must include ref to this file in the build_conf.yaml diff --git a/config/sphinx.yaml b/config/sphinx.yaml deleted file mode 100644 index 9272a19b..00000000 --- a/config/sphinx.yaml +++ /dev/null @@ -1,31 +0,0 @@ -# The items in the ``builders`` list are the name of Sphinx builders -# supported by ``sphinx-build``. -# -# The ``prerequsites`` list stores all targets that must build before -# sphinx can begin. -# -# The ``generated-source`` list stores all the targets that generate rst. - - -prerequisites: - - setup - - intersphinx - - generate-source -generated-source: - - tables - - api - - toc - - intersphinx - - images -### --- #### -web-base: - tags: - - web -### --- #### -dirhtml: - builder: dirhtml - inherit: web-base -html: - builder: html - inherit: web-base -... \ No newline at end of file diff --git a/config/sphinx_local.yaml b/config/sphinx_local.yaml deleted file mode 100644 index 3bd81124..00000000 --- a/config/sphinx_local.yaml +++ /dev/null @@ -1,18 +0,0 @@ -project: 'mongoid-manual' -master_doc: 'index' -logo: ".static/logo.png" -paths: - static: ['source/.static'] -theme: - name: 'mongoid' - project: 'mongoid' - google_analytics: 'UA-7301842-8' - book_path_base: 'mongoid' - repo: 'docs-mongoid' - jira: 'DOCS' - sitename: 'Mongoid' - nav_excluded: [] -sidebars: - '**': - - 'pagenav.html' -... diff --git a/snooty.toml b/snooty.toml index f2840471..6d6f5a8f 100644 --- a/snooty.toml +++ b/snooty.toml @@ -3,9 +3,12 @@ title = "Mongoid" intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv", + "https://www.mongodb.com/docs/drivers/objects.inv", "https://www.mongodb.com/docs/atlas/objects.inv", ] +sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" + toc_landing_pages = [ "/quick-start-rails", "/quick-start-sinatra", @@ -23,6 +26,7 @@ version = "9.0" full-version = "{+version+}.4" ruby-driver = "Ruby driver" language = "Ruby" +ror = "{+language+} on Rails" quickstart-sinatra-app-name = "my-sinatra-app" quickstart-rails-app-name = "my-rails-app" feedback-widget-title = "Feedback" diff --git a/source/.gitignore b/source/.gitignore deleted file mode 100644 index e35d8850..00000000 --- a/source/.gitignore +++ /dev/null @@ -1 +0,0 @@ -_build diff --git a/source/add-existing.txt b/source/add-existing.txt index fdd6fde2..6fa94c9d 100644 --- a/source/add-existing.txt +++ b/source/add-existing.txt @@ -21,7 +21,7 @@ Overview -------- In this guide, you can learn how to add {+odm+} to an existing Sinatra -or Ruby on Rails (Rails) application. To learn how to set up a new +or {+ror+} (Rails) application. To learn how to set up a new application that uses {+odm+}, see one of the following guides: - :ref:`mongoid-quick-start-rails` diff --git a/source/additional-resources.txt b/source/additional-resources.txt index 8de82da5..065b8ee2 100644 --- a/source/additional-resources.txt +++ b/source/additional-resources.txt @@ -26,10 +26,10 @@ Screencasts of setting up an app, querying for documents, adding embedded associations, overriding the id, and more. -- `Ruby on Rails Web Services and Integration with MongoDB, Week 3: Mongoid +- `{+ror+} Web Services and Integration with MongoDB, Week 3: Mongoid `_ - A detailed introduction to Mongoid and Ruby on Rails web services. + A detailed introduction to Mongoid and {+ror+} web services. - `Create a search bar in Rails with Mongoid `_ @@ -48,9 +48,9 @@ Articles Creating a Sinatra API with Mongoid. -- `Converting an existing Ruby on Rails application to MongoDB `_ +- `Converting an existing {+ror+} application to MongoDB `_ - How to Convert an existing Ruby on Rails application to use MongoDB and Mongoid. + How to Convert an existing {+ror+} application to use MongoDB and Mongoid. Sample Applications diff --git a/source/compatibility.txt b/source/compatibility.txt new file mode 100644 index 00000000..d44c016b --- /dev/null +++ b/source/compatibility.txt @@ -0,0 +1,108 @@ +.. _mongoid-compatibility: + +============= +Compatibility +============= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: backwards compatibility, versions, upgrade + +{+language+} Driver Compatibility +------------------------- + +The following compatibility table specifies the versions of the +:ruby:`{+ruby-driver+} ` that are compatible with each +{+odm+} version. + +.. note:: Patch Version Compatibility + + Older patch versions of {+odm+} within the same minor release might + support older {+ruby-driver+} versions. For example, {+odm+} v7.0.5 + supports {+ruby-driver+} v2.5 and later, but {+odm+} v7.0.6 requires + driver v2.7 or later. + +.. include:: /includes/ruby-driver-compatibility-table-mongoid.rst + +MongoDB Compatibility +--------------------- + +The following compatibility table specifies the recommended version or versions +of {+odm+} that you can use with a specific version of MongoDB. To use +features of a particular MongoDB Server version, both the +{+ruby-driver+} and {+odm+} must be compatible with that MongoDB +version. To learn about the driver's MongoDB compatibility details, +see :ruby:`Compatibility ` +in the {+ruby-driver+} documentation. + +The first column lists the version of {+odm+}. + +.. sharedinclude:: dbx/lifecycle-schedule-callout.rst + +.. sharedinclude:: dbx/compatibility-table-legend.rst + +.. include:: /includes/mongodb-compatibility-table-mongoid.rst + +To learn more about how to read the compatibility tables, see the guide +on :ref:`MongoDB Compatibility Tables `. + +Language Compatibility +---------------------- + +The following compatibility table specifies the recommended version or +versions of {+odm+} that you can use with specific {+language+} +interpreter versions. + +The first column lists the version of {+odm+}. + +.. include:: /includes/language-compatibility-table-mongoid.rst + +To learn more about how to read the compatibility tables, see the guide +on :ref:`MongoDB Compatibility Tables `. + +{+ror+} Compatibility +--------------------------- + +The following compatibility table specifies which versions of {+ror+} +are supported by {+odm+}. + +.. include:: /includes/rails-compatibility-table-mongoid.rst + +Rails Frameworks Support +~~~~~~~~~~~~~~~~~~~~~~~~ + +{+odm+} is compatible with many of the frameworks that comprise {+ror+}. +In this section, you can learn about which frameworks you can use with {+odm+}. + +{+odm+} attempts to offer API compatibility with `Active Record +<{+active-record-docs+}/active_record_basics.html>`__, but libraries +that depend directly on Active Record might not work as expected if you +use {+odm+} as a direct replacement. + +.. note:: + + You can use {+odm+} alongside Active Record within the same + application. + +.. include:: /includes/ror-compatibility-table-mongoid.rst + +How to Get Help +--------------- + +If you have questions about compatibility, visit the following resources +for further guidance: + +- Ask questions on our :community-forum:`MongoDB Community Forums <>`. +- Visit the :technical-support:`Support Channels `. +- File an issue or feature request in Jira, our issue tracker. You can + find instructions on filing a ticket on the + :ref:`mongoid-issues-and-help` page. diff --git a/source/ecosystem.txt b/source/ecosystem.txt index a754c45e..9d89cc70 100644 --- a/source/ecosystem.txt +++ b/source/ecosystem.txt @@ -19,7 +19,7 @@ Projects - `Workarea Commerce `_ - Workarea is an enterprise-grade Ruby on Rails commerce platform that uses Mongoid. + Workarea is an enterprise-grade {+ror+} commerce platform that uses Mongoid. Extension Libraries diff --git a/source/includes/language-compatibility-table-mongoid.rst b/source/includes/language-compatibility-table-mongoid.rst new file mode 100644 index 00000000..e7d3b66a --- /dev/null +++ b/source/includes/language-compatibility-table-mongoid.rst @@ -0,0 +1,48 @@ +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :class: compatibility-large + + * - {+odm+} Version + - {+language+} 3.2 + - {+language+} 3.1 + - {+language+} 3.0 + - {+language+} 2.7 + - {+language+} 2.6 + - {+language+} 2.5 + - J{+language+} 9.4 + - J{+language+} 9.3 + - J{+language+} 9.2 + + * - 9.0 + - ✓ + - ✓ + - ✓ + - ✓ + - + - + - ✓ + - + - + + * - 8.1 + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ + - + - + - ✓ + - + + * - 8.0 + - + - ✓ + - ✓ + - ✓ + - ✓ + - + - + - ✓ + - diff --git a/source/includes/mongodb-compatibility-table-mongoid.rst b/source/includes/mongodb-compatibility-table-mongoid.rst new file mode 100644 index 00000000..06fbb6af --- /dev/null +++ b/source/includes/mongodb-compatibility-table-mongoid.rst @@ -0,0 +1,34 @@ +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :class: compatibility-large + + * - {+odm+} Version + - MongoDB 8.0 + - MongoDB 7.0 + - MongoDB 6.0 + - MongoDB 5.0 + - MongoDB 4.4 + - MongoDB 4.2 + - MongoDB 4.0 + - MongoDB 3.6 + + * - 9.0 + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ + + * - 8.0 to 8.1 + - + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ + - ✓ diff --git a/source/includes/rails-compatibility-table-mongoid.rst b/source/includes/rails-compatibility-table-mongoid.rst new file mode 100644 index 00000000..253cd840 --- /dev/null +++ b/source/includes/rails-compatibility-table-mongoid.rst @@ -0,0 +1,52 @@ +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :class: compatibility-large no-padding + + * - {+odm+} Version + - Rails 8.0 + - Rails 7.2 + - Rails 7.1 + - Rails 7.0 + - Rails 6.1 + - Rails 6.0 + - Rails 5.2 + - Rails 5.1 + + * - 9.0 + - ✓ [#rails-8.0]_ + - ✓ [#rails-7.2]_ + - ✓ [#rails-7.1]_ + - ✓ + - ✓ + - ✓ + - + - + + * - 8.1 + - ✓ [#rails-8.0]_ + - ✓ [#rails-7.2]_ + - ✓ [#rails-7.1]_ + - ✓ + - ✓ + - ✓ + - ✓ [#rails-5-ruby-3.0]_ + - + + * - 8.0 + - + - + - ✓ [#rails-7.1]_ + - ✓ + - ✓ + - ✓ + - ✓ [#rails-5-ruby-3.0]_ + - + +.. [#rails-8.0] Rails 8.0 requires {+odm+} v8.1.7 and v9.0.3 in the respective 8.1 and 9.0 stable branches. + +.. [#rails-7.2] Rails 7.2 requires {+odm+} v8.1.6 and v9.0.2 in the respective 8.1 and 9.0 stable branches. + +.. [#rails-7.1] Rails 7.1 requires {+odm+} v8.0.7 or v8.1.3 in the respective 8.0 and 8.1 stable branches. + +.. [#rails-5-ruby-3.0] Using Rails 5.x with Ruby 3 is not supported. diff --git a/source/includes/ror-compatibility-table-mongoid.rst b/source/includes/ror-compatibility-table-mongoid.rst new file mode 100644 index 00000000..b8bd7ee9 --- /dev/null +++ b/source/includes/ror-compatibility-table-mongoid.rst @@ -0,0 +1,70 @@ +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :class: compatibility-large + :widths: 20 20 60 + + * - Rails Framework + - {+odm+} Support + - Notes + + * - ``ActionCable`` + - ✓ + - There is no MongoDB adapter for ``ActionCable``, but you can + use any existing adapter, such as the `Redis Adapter + <{+active-record-docs+}/action_cable_overview.html#redis-adapter>`__, + alongside {+odm+} models. + + * - ``ActionMailbox`` + - *Unsupported* + - Depends directly on Active Record. + + * - ``ActionMailer`` + - ✓ + - + + * - ``ActionPack`` + - ✓ + - + + * - ``ActionText`` + - *Unsupported* + - Depends directly on Active Record. + + * - ``ActionView`` + - ✓ + - + + * - ``ActiveJob`` + - ✓ + - Serialization of BSON and {+odm+} objects works best if you + explicitly send ``BSON::ObjectId`` values as strings, and + reconstitute them in the job. For example: + + .. code-block:: ruby + + record = Model.find(...) + MyJob.perform_later(record._id.to_s) + + class MyJob < ApplicationJob + def perform(id_as_string) + record = Model.find(id_as_string) + # ... + end + end + + * - ``ActiveModel`` + - ✓ + - The ``Mongoid::Document`` module includes + ``ActiveModel::Model`` and leverages ``ActiveModel::Validations`` + for :ref:`mongoid-modeling-validation`. + + * - ``ActiveStorage`` + - *Unsupported* + - Depends directly on Active Record. + + * - ``ActiveSupport`` + - ✓ + - The ``Mongoid`` module requires ``ActiveSupport``. + ``Mongoid`` uses ``ActiveSupport::TimeWithZone`` for handling + time values. diff --git a/source/includes/ruby-driver-compatibility-table-mongoid.rst b/source/includes/ruby-driver-compatibility-table-mongoid.rst new file mode 100644 index 00000000..8eded198 --- /dev/null +++ b/source/includes/ruby-driver-compatibility-table-mongoid.rst @@ -0,0 +1,14 @@ +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :class: compatibility-large + + * - {+odm+} Version + - {+language+} Driver 2.18 to 2.21 + - {+language+} Driver 2.10 to 2.17 + - {+language+} Driver 2.7 to 2.9 + + * - 8.0 to 9.0 + - ✓ + - + - diff --git a/source/index.txt b/source/index.txt index 5ec4d9ba..b3cd4534 100644 --- a/source/index.txt +++ b/source/index.txt @@ -12,7 +12,7 @@ MongoDB in Ruby. To work with {+odm+} from the command line using .. toctree:: :titlesonly: - Quick Start - Ruby on Rails + Quick Start - {+ror+} Quick Start - Sinatra Add {+odm+} to an Existing Application Interact with Data @@ -20,7 +20,8 @@ MongoDB in Ruby. To work with {+odm+} from the command line using Configuration /working-with-data API Documentation - /whats-new + What's New + Compatibility Issues & Help /additional-resources /ecosystem diff --git a/source/installation-configuration.txt b/source/installation-configuration.txt deleted file mode 100644 index fd5ea05b..00000000 --- a/source/installation-configuration.txt +++ /dev/null @@ -1,25 +0,0 @@ -.. _installation-configuration: - -**************************** -Installation & Configuration -**************************** - -.. default-domain:: mongodb - -.. toctree:: - :titlesonly: - - installation - reference/compatibility - reference/configuration - reference/rails-integration - -Overview --------- - -Learn how to install and configure Mongoid in the following sections: - -- :ref:`Installation ` -- :ref:`Compatibility ` -- :ref:`Configuration ` -- :ref:`Rails Integration ` \ No newline at end of file diff --git a/source/installation.txt b/source/installation.txt deleted file mode 100644 index bd9e2908..00000000 --- a/source/installation.txt +++ /dev/null @@ -1,66 +0,0 @@ -.. _installation: - -************ -Installation -************ - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Install the Gem -=============== - -Mongoid is bundled as a gem, and is `hosted on Rubygems -`_. -It can be installed manually or with bundler. - -To install the gem manually: - -.. code-block:: sh - - gem install mongoid - -To install the gem with bundler, include the following in your ``Gemfile``: - -.. code-block:: ruby - - gem 'mongoid' - -Using Mongoid with a New Rails Application -========================================== - -By using the `railsmdb CLI `_ a new -Ruby on Rails application can be quickly generated using the same options as -``rails new``, but configured to work with MongoDB: - -.. code-block:: sh - - railsmdb new my_new_rails_app - -The ``rails`` CLI can also be used, however when creating a new Rails application -and where Mongoid will be used for data access, provide the ``--skip-active-record`` -flag to the ``rails new`` command to avoid depending on and configuring ActiveRecord. - -Additional examples can be found in the `tutorials `_. - -Using Mongoid with an Existing Rails Application -================================================ - -Using the `railsmdb CLI `_ an existing -Rails application can easily be configured for use with Mongoid: - -.. code-block:: sh - - railsmdb setup - -Converting an existing Rails application without using ``railsmdb`` can be done -by updating the ``config/application.rb`` file to remove the ``require 'rails/all'`` -line and explicitly include the required frameworks (which could be all of the -frameworks provided by Rails with the exception ofActiveRecord). -Any references to ActiveRecord in files in the ``config`` directory and in the -models also need to be removed. diff --git a/source/legacy-files/upgrading.txt b/source/legacy-files/upgrading.txt index db27af62..3b5b39bc 100644 --- a/source/legacy-files/upgrading.txt +++ b/source/legacy-files/upgrading.txt @@ -51,7 +51,7 @@ Before you Upgrade - *Test Coverage:* The best way to be sure that your application still works after upgrading is to have good test coverage before you start the process. -- *Upgrade Ruby and Rails:* See `"Upgrading Ruby on Rails" `_ +- *Upgrade Ruby and Rails:* See `"Upgrading {+ror+}" `_ for more information diff --git a/source/nesting-levels.txt b/source/nesting-levels.txt deleted file mode 100644 index 2973410d..00000000 --- a/source/nesting-levels.txt +++ /dev/null @@ -1,20 +0,0 @@ -This file is not part of Mongoid documentation proper, it is an internal -reference for the nesting levels that other files should be using. - -Mongoid documentation nesting levels: - -********** -Page Title -********** - -First Level Heading -=================== - -Second Level Heading --------------------- - -Third Level Heading -``````````````````` - -Fourth Level Heading -~~~~~~~~~~~~~~~~~~~~ diff --git a/source/quick-start-rails.txt b/source/quick-start-rails.txt index 659820ca..f2db9fd5 100644 --- a/source/quick-start-rails.txt +++ b/source/quick-start-rails.txt @@ -1,7 +1,7 @@ .. _mongoid-quick-start-rails: =========================== -Quick Start - Ruby on Rails +Quick Start - {+ror+} =========================== .. facet:: @@ -20,7 +20,7 @@ Quick Start - Ruby on Rails Overview -------- -This guide shows you how to use {+odm+} in a new **Ruby on Rails 8 (Rails)** +This guide shows you how to use {+odm+} in a new **{+ror+} 8 (Rails)** web application, connect to a MongoDB cluster hosted on MongoDB Atlas, and perform read and write operations on the data in your cluster. @@ -38,13 +38,13 @@ To learn how to integrate {+odm+} into an existing application, see the Ruby. By using {+odm+}, you can easily interact with your data and create flexible data models. -Ruby on Rails is a web application framework for +{+ror+} is a web application framework for {+language+}. Rails applications use a model-view-controller (MVC) architecture that allows you to easily control how your data is modeled and displayed. {+odm+} replaces the default Active Record adapter for data modeling in Rails. -To learn more about Ruby on Rails, see the `Getting Started +To learn more about {+ror+}, see the `Getting Started with Rails <{+active-record-docs+}/getting_started.html>`__ guide in the Rails documentation. diff --git a/source/quick-start-rails/download-and-install.txt b/source/quick-start-rails/download-and-install.txt index cca1e8af..cf7ae849 100644 --- a/source/quick-start-rails/download-and-install.txt +++ b/source/quick-start-rails/download-and-install.txt @@ -14,7 +14,7 @@ Download and Install Prerequisites ------------- -To create the Quick Start application by using Ruby on Rails 8, you need the +To create the Quick Start application by using {+ror+} 8, you need the following software installed in your development environment: - `{+language+}. `__ diff --git a/source/quick-start-rails/next-steps.txt b/source/quick-start-rails/next-steps.txt index 9e7bcde4..1869ddf1 100644 --- a/source/quick-start-rails/next-steps.txt +++ b/source/quick-start-rails/next-steps.txt @@ -11,8 +11,7 @@ Next Steps .. meta:: :keywords: learn more -Congratulations on completing the Quick Start tutorial for Ruby on Rails -7! +Congratulations on completing the Quick Start tutorial for {+ror+} 8! After you complete these steps, you have a Rails web application that uses {+odm+} to connect to your MongoDB deployment, run a query on diff --git a/source/quick-start-sinatra.txt b/source/quick-start-sinatra.txt index db7a785d..a5fb7bc7 100644 --- a/source/quick-start-sinatra.txt +++ b/source/quick-start-sinatra.txt @@ -50,7 +50,7 @@ that connects to a MongoDB deployment. .. tip:: Other Framework Tutorials - If you prefer to use Ruby on Rails 8 as your web framework, see the + If you prefer to use {+ror+} 8 as your web framework, see the :ref:`mongoid-quick-start-rails` guide. .. TODO .. tip:: diff --git a/source/reference/compatibility.txt b/source/reference/compatibility.txt deleted file mode 100644 index 7dd2ae19..00000000 --- a/source/reference/compatibility.txt +++ /dev/null @@ -1,507 +0,0 @@ -.. _mongoid-compatibility: - -============= -Compatibility -============= - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Ruby MongoDB Driver Compatibility ---------------------------------- - -The following compatibility table specifies the versions of `Ruby driver for -MongoDB `_ -(the ``mongo`` gem) supported by the most recent patch releases of the -specified Mongoid versions. - -.. note:: - - Older versions of Mongoid within the same minor release may support older - driver versions. For example, Mongoid 7.0.5 supports driver versions 2.5 and - newer, whereas Mongoid 7.0.6 requires driver version 2.7 or newer. - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :class: compatibility-large no-padding - - * - Mongoid - - Driver 2.18+ - - Driver 2.17-2.10 - - Driver 2.9-2.7 - - * - 8.0 through 9.0 - - |checkmark| - - - - - - * - 7.2 through 7.5 - - |checkmark| - - |checkmark| - - - - * - 7.0 through 7.1 - - |checkmark| - - |checkmark| - - |checkmark| - - -Ruby Compatibility ------------------- - -The following compatibility table specifies the versions of Ruby interpreters -supported by Mongoid. "D" in a column means support for that Ruby version -is deprecated. - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :class: compatibility-large no-padding - - * - Mongoid - - Ruby 3.2 - - Ruby 3.1 - - Ruby 3.0 - - Ruby 2.7 - - Ruby 2.6 - - Ruby 2.5 - - Ruby 2.4 - - Ruby 2.3 - - Ruby 2.2 - - JRuby 9.4 - - JRuby 9.3 - - JRuby 9.2 - - * - 9.0 - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - - - |checkmark| - - - - - - * - 8.1 - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - - - |checkmark| - - - - * - 8.0 - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - - - |checkmark| - - - - * - 7.5 - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - D - - - - - - - - - - |checkmark| - - D - - * - 7.4 - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - - - |checkmark| - - * - 7.3 - - - - |checkmark| [#mongoid-7.3-ruby-3.0]_ - - |checkmark| [#mongoid-7.3-ruby-3.0]_ - - |checkmark| - - |checkmark| - - |checkmark| - - D - - D - - - - - - - - |checkmark| - - * - 7.2 - - - - |checkmark| [#mongoid-7.2-ruby-3.0]_ - - |checkmark| [#mongoid-7.2-ruby-3.0]_ - - |checkmark| - - |checkmark| - - |checkmark| - - D - - D - - - - - - - - |checkmark| - - * - 7.1 - - - - |checkmark| [#mongoid-7.1-ruby-3.0]_ - - |checkmark| [#mongoid-7.1-ruby-3.0]_ - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| [#ruby-2.4]_ - - |checkmark| - - - - - - - - |checkmark| - - * - 7.0 - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| [#ruby-2.4]_ - - |checkmark| - - |checkmark| [#ruby-2.2]_ - - - - - - |checkmark| - -.. [#mongoid-7.3-ruby-3.0] Mongoid version 7.3.2 or higher is required. - -.. [#mongoid-7.2-ruby-3.0] Mongoid version 7.2.5 or higher is required. - -.. [#mongoid-7.1-ruby-3.0] Mongoid version 7.1.10 or higher is required. - -.. [#ruby-2.4] Ruby version 2.4.1 or higher is required. - -.. [#ruby-2.2] Ruby version 2.2.2 or higher is required. - - -MongoDB Server Compatibility ----------------------------- - -The following compatibility table specifies the recommended -version(s) of Mongoid for use with a specific version of MongoDB server. - -Note that in order to use features of a particular MongoDB server version, -both the driver and Mongoid must support that server version. -Please refer to `the driver compatibility page -`_ -for driver compatibility matrices. - -"D" in a column means support for that MongoDB server version is deprecated -and will be removed in a next version. - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :class: compatibility-large no-padding - - * - Mongoid - - MongoDB 8.0 - - MongoDB 7.0 - - MongoDB 6.0 - - MongoDB 5.0 - - MongoDB 4.4 - - MongoDB 4.2 - - MongoDB 4.0 - - MongoDB 3.6 - - MongoDB 3.4 - - MongoDB 3.2 - - MongoDB 3.0 - - MongoDB 2.6 - - * - 9.0+ - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - * - 8.0 through 9.0 - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - - - - - * - 7.4 through 7.5 - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - D - - D - - D - - D - - * - 7.0 through 7.3 - - - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| - - D - - D - - D - - D - - -.. _rails-compatibility: - -Rails Compatibility -------------------- - -The following compatibility table specifies which versions of Ruby on Rails -are supported by Mongoid. - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :class: compatibility-large no-padding - - * - Mongoid - - Rails 7.2 - - Rails 7.1 - - Rails 7.0 - - Rails 6.1 - - Rails 6.0 - - Rails 5.2 - - Rails 5.1 - - * - 9.0 - - |checkmark| [#rails-7.2]_ - - |checkmark| [#rails-7.1]_ - - |checkmark| - - |checkmark| - - |checkmark| - - - - - - * - 8.1 - - |checkmark| [#rails-7.2]_ - - |checkmark| [#rails-7.1]_ - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| [#rails-5-ruby-3.0]_ - - - - * - 8.0 - - - - |checkmark| [#rails-7.1]_ - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| [#rails-5-ruby-3.0]_ - - - - * - 7.5 - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| [#rails-5-ruby-3.0]_ - - D - - * - 7.4 - - - - - - |checkmark| - - |checkmark| - - |checkmark| - - |checkmark| [#rails-5-ruby-3.0]_ - - |checkmark| [#rails-5-ruby-3.0]_ - - * - 7.3 - - - - - - |checkmark| [#rails-7-Mongoid-7.3]_ - - |checkmark| - - |checkmark| - - |checkmark| [#rails-5-ruby-3.0]_ - - |checkmark| [#rails-5-ruby-3.0]_ - - * - 7.2 - - - - - - - - |checkmark| [#rails-6.1]_ - - |checkmark| - - |checkmark| [#rails-5-ruby-3.0]_ - - |checkmark| [#rails-5-ruby-3.0]_ - - * - 7.1 - - - - - - - - |checkmark| [#rails-6.1]_ - - |checkmark| - - |checkmark| - - |checkmark| - - * - 7.0 - - - - - - - - |checkmark| [#rails-6.1]_ - - |checkmark| [#rails-6]_ - - |checkmark| - - |checkmark| - -.. [#rails-5-ruby-3.0] Using Rails 5.x with Ruby 3 is not supported. - -.. [#rails-6] Rails 6.0 requires Mongoid 7.0.5 or later. - -.. [#rails-6.1] Rails 6.1 requires Mongoid 7.0.12, 7.1.7 or 7.2.1 in the - respective 7.0, 7.1 and 7.2 stable branches. - -.. [#rails-7-Mongoid-7.3] Rails 7.x requires Mongoid 7.3.4 or later. - -.. [#rails-7.1] Rails 7.1 requires Mongoid 8.0.7 or 8.1.3 in the respective - 8.0 and 8.1 stable branches. - -.. [#rails-7.2] Rails 7.2 requires Mongoid 8.1.6 and 9.0.2 in the respective - 8.1 and 9.0 stable branches. - -.. include:: /includes/unicode-checkmark.rst -.. include:: /includes/unicode-ballot-x.rst - -Rails Frameworks Support -~~~~~~~~~~~~~~~~~~~~~~~~ - -Ruby on Rails is comprised of a number of frameworks, which Mongoid attempts to -provide compatibility with wherever possible. - -Though Mongoid attempts to offer API compatibility with `Active Record `_, -libraries that depend directly on Active Record may not work as expected when -Mongoid is used as a drop-in replacement. - -.. note:: - - Mongoid can be used alongside Active Record within the same application without issue. - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :class: compatibility-large no-padding - - * - Rails Framework - - Supported? - - * - ``ActionCable`` - - |checkmark| [#rails-actioncable-dependency]_ - - * - ``ActionMailbox`` - - |x| [#rails-activerecord-dependency]_ - - * - ``ActionMailer`` - - |checkmark| - - * - ``ActionPack`` - - |checkmark| - - * - ``ActionText`` - - |x| [#rails-activerecord-dependency]_ - - * - ``ActionView`` - - |checkmark| - - * - ``ActiveJob`` - - |checkmark| [#rails-activejob-dependency]_ - - * - ``ActiveModel`` - - |checkmark| [#rails-activemodel-dependency]_ - - * - ``ActiveStorage`` - - |x| [#rails-activerecord-dependency]_ - - * - ``ActiveSupport`` - - |checkmark| [#rails-activesupport-dependency]_ - -.. [#rails-actioncable-dependency] There is currently no MongoDB adapter for - ``ActionCable``, however any existing adapter (such as `Redis `_) - can be used successfully in conjunction with Mongoid models - -.. [#rails-activerecord-dependency] Depends directly on ActiveRecord - -.. [#rails-activemodel-dependency] ``Mongoid::Document`` includes ``ActiveModel::Model`` - and leverages ``ActiveModel::Validations`` for validations - -.. [#rails-activesupport-dependency] ``Mongoid`` requires ``ActiveSupport`` and - uses it extensively, including ``ActiveSupport::TimeWithZone`` for time handling. - - - -.. [#rails-activejob-dependency] Serialization of BSON & Mongoid objects works best - if you explicitly send ``BSON::ObjectId``'s as strings, and reconstitute them in the job: - - .. code-block:: ruby - - record = Model.find(...) - MyJob.perform_later(record._id.to_s) - - class MyJob < ApplicationJob - def perform(id_as_string) - record = Model.find(id_as_string) - # ... - end - end diff --git a/source/reference/configuration.txt b/source/reference/configuration.txt index 2d82faf2..c948673d 100644 --- a/source/reference/configuration.txt +++ b/source/reference/configuration.txt @@ -36,7 +36,7 @@ Most applications will use a single client named ``default``. Generating Default Configuration ================================ -If you are using Ruby on Rails, you can have Mongoid generate a default +If you are using {+ror+}, you can have Mongoid generate a default configuration file for you by running the following command: .. code-block:: bash @@ -51,14 +51,14 @@ initializer may also be used to set configuration options. Note, though, that settings in ``mongoid.yml`` always take precedence over settings in the initializer. -If you are not using Ruby on Rails, you can copy the minimal configuration +If you are not using {+ror+}, you can copy the minimal configuration given above and save it as ``config/mongoid.yml``. Loading Mongoid Configuration ============================= -If you are using Ruby on Rails, Mongoid configuration is automatically loaded +If you are using {+ror+}, Mongoid configuration is automatically loaded for the current environment as stored in ``Rails.env`` when the application loads. @@ -71,7 +71,7 @@ adding the following to ``application.rb``: g.orm :mongoid end -If you are not using Ruby on Rails, Mongoid configuration must be loaded +If you are not using {+ror+}, Mongoid configuration must be loaded manually. This can be done via the ``Mongoid.load!`` method, which takes the configuration file path as its argument, as follows: @@ -509,14 +509,14 @@ logger. In other words: # Ruby driver logger, not Mongoid logger Mongoid.client(:default).logger -Depending on whether Mongoid is used in a Ruby on Rails application, and how +Depending on whether Mongoid is used in a {+ror+} application, and how both Mongoid and Ruby driver are configured, they may use the same logger instance or different instances, potentially with different configurations. -In Ruby on Rails Application +In {+ror+} Application ---------------------------- -When used in a Ruby on Rails application, Mongoid by default inherits +When used in a {+ror+} application, Mongoid by default inherits the logger and the log level from Rails, and sets the driver's logger to the same logger instance: @@ -588,7 +588,7 @@ use an initializer as follows: Standalone ---------- -When not loaded in a Ruby on Rails application, Mongoid respects the +When not loaded in a {+ror+} application, Mongoid respects the ``log_level`` top level configuration option. It can be given in the configuration file as follows: @@ -963,7 +963,7 @@ Enabling Query Cache for Rack Web Requests The MongoDB Ruby Driver provides a Rack middleware which enables the :ref:`Query Cache ` for the duration of each web request. Below is an example of -how to enable the Query Cache Middleware in a Ruby on Rails application: +how to enable the Query Cache Middleware in a {+ror+} application: .. code-block:: ruby diff --git a/source/reference/rails-integration.txt b/source/reference/rails-integration.txt index 0a43d96d..15ea483a 100644 --- a/source/reference/rails-integration.txt +++ b/source/reference/rails-integration.txt @@ -12,7 +12,7 @@ Rails Integration :depth: 2 :class: singlecol -Mongoid seamlessly integrates into Ruby on Rails applications. +Mongoid seamlessly integrates into {+ror+} applications. This page describes features that are automatically enabled in the context of a Rails application and Rails-related functionality which can be manually enabled. diff --git a/source/release-notes.txt b/source/release-notes.txt deleted file mode 100644 index 27127103..00000000 --- a/source/release-notes.txt +++ /dev/null @@ -1,31 +0,0 @@ -.. _release-notes: - -************* -Release Notes -************* - -.. default-domain:: mongodb - -.. toctree:: - :titlesonly: - - release-notes/upgrading - release-notes/mongoid-9.0 - release-notes/mongoid-8.1 - release-notes/mongoid-8.0 - release-notes/mongoid-7.5 - release-notes/mongoid-7.4 - release-notes/mongoid-7.3 - -Overview --------- - -See the following sections to learn more about upgrading Mongoid: - -- :ref:`Upgrading Mongoid ` -- :ref:`Mongoid 9.0 ` -- :ref:`Mongoid 8.1 ` -- :ref:`Mongoid 8.0 ` -- :ref:`Mongoid 7.5 ` -- :ref:`Mongoid 7.4 ` -- :ref:`Mongoid 7.3 ` \ No newline at end of file diff --git a/source/whats-new.txt b/source/whats-new.txt index e6b0bbd7..e6e52baa 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -33,7 +33,7 @@ for creating, updating, managing, and maintaining Rails applications, is generally available. ``railsmdb`` makes it easier to work with MongoDB from the command line -through common generators that {+language+} on Rails developers are already +through common generators that {+ror+} developers are already familiar with. For example, you can use ``railsmdb`` to generate stubs for new {+odm+} models: diff --git a/source/working-with-data.txt b/source/working-with-data.txt deleted file mode 100644 index 96ab61dc..00000000 --- a/source/working-with-data.txt +++ /dev/null @@ -1,37 +0,0 @@ -.. _working-with-data: - -***************** -Working With Data -***************** - -.. default-domain:: mongodb - -.. toctree:: - :titlesonly: - - reference/crud - reference/queries - reference/text-search - /aggregation - reference/map-reduce - reference/persistence-configuration - reference/nested-attributes - reference/callbacks - reference/sessions - reference/transactions - -Overview --------- - -See the following sections to learn more about working with data in Mongoid: - -- :ref:`CRUD Operations ` -- :ref:`Queries ` -- :ref:`Text Search ` -- :ref:`mongoid-aggregation` -- :ref:`Map/Reduce ` -- :ref:`Persistence Configuration ` -- :ref:`Nested Attributes ` -- :ref:`Callbacks ` -- :ref:`Sessions ` -- :ref:`Transactions ` \ No newline at end of file