Update documentation for 1.1.0 #276

jmikola · 2016-10-28T00:59:35Z

https://jira.mongodb.org/browse/PHPLIB-186
https://jira.mongodb.org/browse/PHPLIB-221

jmikola · 2016-11-01T16:22:55Z

docs/includes/apiargs-MongoDBClient-method-construct-driverOptions.yaml

+  to apply to cursors, which determines how BSON documents are converted to PHP
+  values. The |php-library| uses the following type map by default:
+
+  .. code-block:: php


YAML uses a 2-space indent, so I'm using that for the description indent level; however, the contents uses a 3-space indent to be consistent with RST sources.

I also stuck with an 80-char wrap for consistency with PHPLIB, which admittedly differs from the manual's 72-char wrap.

jmikola · 2016-11-01T17:42:01Z

docs/includes/apiargs-MongoDBCollection-common-option.yaml

+   If ``true``, allows the write operation to circumvent document level
+   validation. Defaults to ``false``.
+interface: phpmethod
+operation: ~


@schmalliso noted that operation, while a required key in the Python model, is only used for replacing {{role}} in content. I decided to use operation: ~ (i.e. null) for common option/param definitions and will probably do so for all definitions.

jmikola · 2016-11-01T17:43:06Z

docs/includes/apiargs-MongoDBClient-method-construct-param.yaml

 interface: phpmethod
 operation: MongoDB\\Client::__construct
 optional: true
-position: 1


I found that position was not required by the model. By default, the order is derived from the YAML file's own ordering (starting with 1 and incrementing with each new definition).

jmikola · 2016-11-01T17:43:45Z

docs/includes/apiargs-MongoDBCollection-method-aggregate-option.yaml

-operation: MongoDB\\Collection::aggregate
-position: 5
+post: |
+  This only applies when using the :pipeline:`$out` stage.


For my local builds, :pipline: was not resolved as a link and merely applied fixed-width formatting to "$out". Is that intentional?

That happens if a link is not resolved. This is bad enough, but Sphinx won't resolve links to a pipeline/method/whatever defined on the same page.

Is this just a byproduct of me rendering the PHPLIB docs separately from the main manual (on my local machine), or do you expect this would persist even in the final builds. I might as well just use $out if this will have no effect in the deployed version.

Yeah, just use double-ticks.

@schmalliso is creating a ref link in the MongoDB manual for this: agg-out.

jmikola · 2016-11-01T17:48:24Z

docs/reference/method/MongoDBCollection-createIndexes.txt

-   You can specify any index options that your MongoDB version
-   supports. MongoDB 3.2 includes the following options:
-
-   .. include:: /includes/apiargs/MongoDBCollection-method-createIndex-option.rst


After adding the actual parameter and options includes for this method, which differ from createIndex(), I tried moving the general index options into a section below entitled "$indexes parameter". I found that the table didn't render the same as this "Definition" section (with leading indentation). The second paragraph of each option description would increase in font size, which is likely a CSS issue.

Ultimately, I decided not to repeat the index options and instead link to createIndex() and the MongoDB manual. I feel this also works better because writeConcern is one of the createIndex() method options despite the fact that it's not an index option. Maintaining a separate include of just index options and writeConcern seemed like a fair bit of overhead. As-is, explaining how $indexes works in its own section below makes createIndexes() method docs easier to digest, since we only discuss the actual params/options in the "Definition" section.

jmikola · 2016-11-01T17:52:18Z

docs/reference/method/MongoDBClient-dropDatabase.txt


   .. include:: /includes/apiargs/MongoDBClient-method-dropDatabase-option.rst

-Output
------
+   :returns:


I spoke to @kay-kim about "Output" vs. :returns: and she said the manual tends to use :returns: for one-liners and "Output" for larger descriptions. I may want to switch this back to its own heading, since the :returns: output does look a bit crowded for multiple lines of text.

The PHP.net documentation has actual headings for "Errors" and "Return Values", so I will probably mimic that. "Output" doesn't quite make as much sense for PHPLIB as it does for the MongoDB shell, since our return values are not implicitly printed to a console.

Currently, I'm using :returns: everywhere so we can probably leave it as-is in this PR and I'll revise this later when also documenting our exceptions.

jmikola · 2016-11-01T17:54:04Z

docs/reference/method/MongoDBClient-listDatabases.txt


   .. code-block:: php

      function listDatabases(array $options = []): MongoDB\Model\DatabaseInfoIterator

-   :phpmethod:`MongoDB\\Client::listDatabases` has the following parameters:
+   :phpmethod:`MongoDB\\Client::listDatabases()` has the following parameters:


Is there value in using a :phpmethod: reference here instead of saying "This method"? I noticed that it only renders as fixed-width text instead of a link to the current page. Considering that we already repeat the method name twice immediately before this, I'm dubious that this is any better than common text like I'm using below for $options.

I generally suggest not using role-links to things defined on the current page, since they don't render the way humans would expect.

jmikola · 2016-11-01T17:55:57Z

docs/reference/method/MongoDBGridFSBucket-downloadToStreamByName.txt

+
+   .. include:: /includes/apiargs/MongoDBGridFSBucket-method-downloadToStreamByName-option.rst
+
+.. todo: add examples


Does .. todo actually render any output or is there merely an internal comment that the docs team can use to find areas needing improvement down the line?

It's just a comment.

RestructuredText is weird: anything starting with two periods .. is a comment, UNLESS the first word ends with a double-colon ::, in which case it's a directive.

See: mongodb/docs@2a91231

jmikola · 2016-11-01T19:44:22Z

docs/includes/apiargs-MongoDBGridFSBucket-method-find-option.yaml

+  file: apiargs-MongoDBCollection-method-find-option.yaml
+  ref: typeMap
+replacement:
+  parent: "bucket"


This will depend on PHPLIB-232.

jmikola added 2 commits October 27, 2016 11:53

Revise Collection and Database class intros

ec1ae3a

PHPLIB-186: Document getManager() methods

470a904

jmikola force-pushed the 1.1-docs branch 3 times, most recently from 652635a to 5275b6c Compare October 31, 2016 20:48

jmikola added 9 commits October 31, 2016 18:51

Update MongoDB\Client documentation

1892dc6

Fix language for $databaseName and $collectionName params

cbb7f43

Update MongoDB\Database documentation

6d4a1d3

Use common param for $manager

9a5c329

Fix typo in Aggregate docs

b12430a

Update MongoDB\Collection documentation

b33e5a5

PHPLIB-221: API documentation for MongoDB\GridFS\Bucket

4955333

PHPLIB-197: Fix typo in uploadFromStream() docs

af2affc

PHPLIB-221: GridFS tutorial documentation

12f583d

jmikola force-pushed the 1.1-docs branch from 5275b6c to caa5c3d Compare November 1, 2016 06:51

jmikola mentioned this pull request Nov 1, 2016

GridFS file uploads broken #210

Closed

jmikola commented Nov 1, 2016

View reviewed changes

Refactor option/param includes and document MongoDB 3.4 features

9a53ec6

jmikola force-pushed the 1.1-docs branch from caa5c3d to 9a53ec6 Compare November 1, 2016 19:02

jmikola added 3 commits November 1, 2016 15:08

Use "agg-out" reference in MongoDB manual

c0e0ebc

See: mongodb/docs@2a91231

Use generic language for documenting method params

3026b3c

Extend Collection::find() options for Bucket instead of including as-is

c63ca8d

jmikola commented Nov 1, 2016

View reviewed changes

jmikola merged commit c63ca8d into mongodb:master Nov 1, 2016

jmikola added a commit that referenced this pull request Nov 1, 2016

Merge pull request #276

83eb398

jmikola changed the title ~~[WIP] Update documentation for 1.1.0~~ Update documentation for 1.1.0 Nov 1, 2016

jmikola deleted the 1.1-docs branch November 1, 2016 19:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Update documentation for 1.1.0 #276

Update documentation for 1.1.0 #276

Uh oh!

jmikola commented Oct 28, 2016 •

edited

Loading

Uh oh!

jmikola Nov 1, 2016

Uh oh!

jmikola Nov 1, 2016

Uh oh!

jmikola Nov 1, 2016

Uh oh!

jmikola Nov 1, 2016

Uh oh!

i80and Nov 1, 2016

Uh oh!

jmikola Nov 1, 2016

Uh oh!

i80and Nov 1, 2016

Uh oh!

jmikola Nov 1, 2016

Uh oh!

jmikola Nov 1, 2016

Uh oh!

jmikola Nov 1, 2016

Uh oh!

jmikola Nov 1, 2016

Uh oh!

i80and Nov 1, 2016

Uh oh!

jmikola Nov 1, 2016

Uh oh!

i80and Nov 1, 2016

Uh oh!

jmikola Nov 1, 2016

Uh oh!

Uh oh!


		.. include:: /includes/apiargs/MongoDBGridFSBucket-method-downloadToStreamByName-option.rst

		.. todo: add examples

Update documentation for 1.1.0 #276

Update documentation for 1.1.0 #276

Uh oh!

Conversation

jmikola commented Oct 28, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jmikola commented Oct 28, 2016 •

edited

Loading