PHPLIB-989: Move persistable class documentation to tutorial

[alcaeus]

PHPLIB-989

This moves the documentation on classes implementing MongoDB\BSON\Persistable from the BSON reference to a tutorial. It was already written as a tutorial, and linking it as a tutorial on the homepage will make it more visible to users.

I've also considered doing the same with the Type Map information, but considering that persistable classes cover typemap functionality as well, I'm not sure we'll want to. Any opinions @jmikola?

[jmikola]

I've also considered doing the same with the Type Map information, but considering that persistable classes cover typemap functionality as well, I'm not sure we'll want to.

The BSON reference page was always a bit of a dumping ground. I do think it'd make it makes sense to extract its sections out to other pages.

I'd suggest splitting Type Maps off to its own page or combining with the Persistable Classes tutorial page you're creating here.

Emulating the Legacy Driver can be moved to the Upgrade Guide, which I believe you already plan to rename to "Legacy Driver Upgrade Guide" (or something to that effect). For that, I'd suggest renaming BSON Type Classes to "Type Classes" and placing the "Emulating" section parallel to that under a new, top-level "BSON" heading.

That would just leave the BSON reference page with two sections: Overview and BSON Classes. From there, I'd suggest renaming "BSON Classes" to just "Classes". Those remaining two sections would be appropriate for a reference page, and then you could also add "See Also" links to the newly created tutorial page(s) and relocated "Emulating the Legacy Driver" section.

[alcaeus]

@jmikola great suggestions - I applied them as suggested.

[jmikola]

Let me know when the suggestions are applied and I'll check out the PR for a local docs build to inspect before merging. IIRC, you had some trouble with local docs builds.

[jmikola]

Content LGTM. I'll leave you to verify that RST build, since my Giza build environment is broken.

[jmikola]

since my Giza build environment is broken.

Just fixed it and was able to preview this PR. Everything looks good.