DRIVERS-2881 Render documentation on ReadTheDocs

.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+ os: ubuntu-22.04
+ tools:
+ python: "3.12"
+
+mkdocs:
+ configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+ install:
+ - requirements: source/requirements.txt

README.md

@@ -1,77 +1,13 @@
 # MongoDB Specifications
 
+[![Documentation Status](https://readthedocs.org/projects/specifications/badge/?version=latest)](http://specifications.readthedocs.io/en/latest/?badge=latest)
+
 This repository holds in progress and completed specification for features of MongoDB, Drivers, and associated products.
 Also contained is a rudimentary system for producing these documents.
 
 ## Driver Mantras
 
-When developing specifications -- and the drivers themselves -- we follow the following principles:
-
-### Strive to be idiomatic, but favor consistency
-
-Drivers attempt to provide the easiest way to work with MongoDB in a given language ecosystem, while specifications
-attempt to provide a consistent behavior and experience across all languages. Drivers should strive to be as idiomatic
-as possible while meeting the specification and staying true to the original intent.
-
-### No Knobs
-
-Too many choices stress out users. Whenever possible, we aim to minimize the number of configuration options exposed to
-users. In particular, if a typical user would have no idea how to choose a correct value, we pick a good default instead
-of adding a knob.
-
-### Topology agnostic
-
-Users test and deploy against different topologies or might scale up from replica sets to sharded clusters. Applications
-should never need to use the driver differently based on topology type.
-
-### Where possible, depend on server to return errors
-
-The features available to users depend on a server's version, topology, storage engine and configuration. So that
-drivers don't need to code and test all possible variations, and to maximize forward compatibility, always let users
-attempt operations and let the server error when it can't comply. Exceptions should be rare: for cases where the server
-might not error and correctness is at stake.
-
-### Minimize administrative helpers
-
-Administrative helpers are methods for admin tasks, like user creation. These are rarely used and have maintenance costs
-as the server changes the administrative API. Don't create administrative helpers; let users rely on "RunCommand" for
-administrative commands.
-
-### Check wire version, not server version
-
-When determining server capabilities within the driver, rely only on the maxWireVersion in the hello response, not on
-the X.Y.Z server version. An exception is testing server development releases, as the server bumps wire version early
-and then continues to add features until the GA.
-
-### When in doubt, use "MUST" not "SHOULD" in specs
-
-Specs guide our work. While there are occasionally valid technical reasons for drivers to differ in their behavior,
-avoid encouraging it with a wishy-washy "SHOULD" instead of a more assertive "MUST".
-
-### Defy augury
-
-While we have some idea of what the server will do in the future, don't design features with those expectations in mind.
-Design and implement based on what is expected in the next release.
-
-Case Study: In designing OP_MSG, we held off on designing support for Document Sequences in Replies in drivers until the
-server would support it. We subsequently decided not to implement that feature in the server.
-
-### The best way to see what the server does is to test it
-
-For any unusual case, relying on documentation or anecdote to anticipate the server's behavior in different
-versions/topologies/etc. is error-prone. The best way to check the server's behavior is to use a driver or the shell and
-test it directly.
-
-### Drivers follow semantic versioning
-
-Drivers should follow X.Y.Z versioning, where breaking API changes require a bump to X. See
-[semver.org](https://semver.org/) for more.
-
-### Backward breaking behavior changes and semver
-
-Backward breaking behavior changes can be more dangerous and disruptive than backward breaking API changes. When
-thinking about the implications of a behavior change, ask yourself what could happen if a user upgraded your library
-without carefully reading the changelog and/or adequately testing the change.
+See [Documentation](./source/driver-mantras.md).
 
 ## Writing Documents
 
@@ -110,13 +46,11 @@ entire test with a note (e.g. *Removed*).
 
 ## Building Documents
 
-We build the docs in `text` mode in CI to make sure they build without errors. We don't actually support building html,
-since we rely on GitHub to render the documents. To build locally, run:
+We use [mkdocs](https://www.mkdocs.org/) to render the documentation. To see a live view of the documentation, run:
 
 ```bash
-pip install sphinx
-cd source 
-sphinx-build -W -b text . docs_build index.rst
+pip install mkdocs
+mkdocs serve
 ```
 
 ## Converting to JSON

mkdocs.yml

@@ -0,0 +1,4 @@
+site_name: MongoDB Specifications
+docs_dir: source
+nav:
+ - 'index.md'

source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md

@@ -1265,8 +1265,8 @@ longer full, it is immediately filled. It is not a favorable situation to be in,
 guarantee that the waitQueue normally provides.
 
 Because of these issues, it does not make sense to
-[go against driver mantras and provide an additional knob](../../README.md#). We may eventually pursue an alternative
-configurations to address wait queue size in [Advanced Pooling Behaviors](#advanced-pooling-behaviors).
+[go against driver mantras and provide an additional knob](../driver-mantras.md#). We may eventually pursue an
+alternative configuration to address wait queue size in [Advanced Pooling Behaviors](#advanced-pooling-behaviors).
 
 Users that wish to have this functionality can achieve similar results by utilizing other methods to limit concurrency.
 Examples include implementing either a thread pool or an operation queue with a capped size in the user application.

source/driver-mantras.md

@@ -0,0 +1,69 @@
+# Driver Mantras
+
+When developing specifications -- and the drivers themselves -- we follow the following principles:
+
+### Strive to be idiomatic, but favor consistency
+
+Drivers attempt to provide the easiest way to work with MongoDB in a given language ecosystem, while specifications
+attempt to provide a consistent behavior and experience across all languages. Drivers should strive to be as idiomatic
+as possible while meeting the specification and staying true to the original intent.
+
+### No Knobs
+
+Too many choices stress out users. Whenever possible, we aim to minimize the number of configuration options exposed to
+users. In particular, if a typical user would have no idea how to choose a correct value, we pick a good default instead
+of adding a knob.
+
+### Topology agnostic
+
+Users test and deploy against different topologies or might scale up from replica sets to sharded clusters. Applications
+should never need to use the driver differently based on topology type.
+
+### Where possible, depend on server to return errors
+
+The features available to users depend on a server's version, topology, storage engine and configuration. So that
+drivers don't need to code and test all possible variations, and to maximize forward compatibility, always let users
+attempt operations and let the server error when it can't comply. Exceptions should be rare: for cases where the server
+might not error and correctness is at stake.
+
+### Minimize administrative helpers
+
+Administrative helpers are methods for admin tasks, like user creation. These are rarely used and have maintenance costs
+as the server changes the administrative API. Don't create administrative helpers; let users rely on "RunCommand" for
+administrative commands.
+
+### Check wire version, not server version
+
+When determining server capabilities within the driver, rely only on the maxWireVersion in the hello response, not on
+the X.Y.Z server version. An exception is testing server development releases, as the server bumps wire version early
+and then continues to add features until the GA.
+
+### When in doubt, use "MUST" not "SHOULD" in specs
+
+Specs guide our work. While there are occasionally valid technical reasons for drivers to differ in their behavior,
+avoid encouraging it with a wishy-washy "SHOULD" instead of a more assertive "MUST".
+
+### Defy augury
+
+While we have some idea of what the server will do in the future, don't design features with those expectations in mind.
+Design and implement based on what is expected in the next release.
+
+Case Study: In designing OP_MSG, we held off on designing support for Document Sequences in Replies in drivers until the
+server would support it. We subsequently decided not to implement that feature in the server.
+
+### The best way to see what the server does is to test it
+
+For any unusual case, relying on documentation or anecdote to anticipate the server's behavior in different
+versions/topologies/etc. is error-prone. The best way to check the server's behavior is to use a driver or the shell and
+test it directly.
+
+### Drivers follow semantic versioning
+
+Drivers should follow X.Y.Z versioning, where breaking API changes require a bump to X. See
+[semver.org](https://semver.org/) for more.
+
+### Backward breaking behavior changes and semver
+
+Backward breaking behavior changes can be more dangerous and disruptive than backward breaking API changes. When
+thinking about the implications of a behavior change, ask yourself what could happen if a user upgraded your library
+without carefully reading the changelog and/or adequately testing the change.

source/index.md

@@ -13,6 +13,7 @@
 - [Connection String Spec](connection-string/connection-string-spec.md)
 - [Driver Authentication](auth/auth.md)
 - [Driver CRUD API](crud/crud.md)
+- [Driver Mantras](./driver-mantras.md)
 - [Driver Sessions Specification](sessions/driver-sessions.md)
 - [Driver Transactions Specification](transactions/transactions.md)
 - [FaaS Automated Testing](faas-automated-testing/faas-automated-testing.md)

source/requirements.txt

@@ -0,0 +1 @@
+mkdocs