DOCSP-36027: Shorten class headings #1229

norareidy · 2024-02-08T19:16:53Z

This PR includes all the tickets in this JIRA epic, which shorten the titles of API documentation pages.

Note: I also restructured the TOC a little by adding new drawers with class methods. This might be slightly out of scope for DOCSP-36027, but it seemed like the best way to reduce page titles enough so that they fit in the sidebar but don't omit necessary context (i.e., which class they belong to).

Staging: https://preview-mongodbnorareidy.gatsbyjs.io/php-library/DOCSP-36027/reference/

GromNaN

While reviewing the preview page, I spotted some issues that might be related to your change. Could you fix them directly in this PR, or create jira issues for later?

Staging: https://preview-mongodbnorareidy.gatsbyjs.io/php-library/DOCSP-36027/reference/

Why is this particular page empty?

.vscode/settings.json

GromNaN · 2024-02-09T09:05:03Z

docs/reference/class/MongoDBBulkWriteResult.txt

+   /reference/method/MongoDBBulkWriteResult-getUpsertedIds
+   /reference/method/MongoDBBulkWriteResult-isAcknowledged
+
+- :phpmethod:`MongoDB\\BulkWriteResult::getDeletedCount()`


The the double backslashes are usually used for escaping but it looks like it's not necessary. On staging, I see double backslashes in all namespaces. A single backslash should be displayed.

Just to clarify: every namespace mentioned in the docs should use one instead of two backslashes? If so, I'm happy to fix the backslashes in this PR - or make a new ticket, since it seems like all the namespaces currently have two backslashes and many files would need to be modified

It's always one backslash. The double backslash doesn't exist in PHP namespaces.

The double backslashes were necessary for escaping syntax in RST; however, I think that was only relevant for actual headings and not cases where text is monospace-formatted. I only recently noticed that double backslashes showing up in some monospace-formatted text (as shown in @GromNaN's screenshot above), but I'm not sure if that was recently introduced by some layout changes or a very old mistake that went unnoticed until now.

Tracked by @norareidy in DOCSP-36627

docs/reference/class/MongoDBModelIndexInfo.txt

GromNaN · 2024-02-09T09:15:41Z

docs/reference/method/MongoDBClient-addSubscriber.txt

Adding the comment here for the thread. Not related to this file.

Not a regression but a bug that you might fix here: the page on the MongoDB\Client class have lost the list of methods
https://www.mongodb.com/docs/php-library/current/reference/class/MongoDBClient/

I actually noticed this about all the "Methods" sections (on MongoDB\Client, MongoDB\Database, MongoDB\Collection, etc). I'll fix the rendering issues in this PR

Alright fixed!

mongoKart

shortened headings LGTM, assuming DBX is on board!

norareidy · 2024-02-12T15:57:17Z

While reviewing the preview page, I spotted some issues that might be related to your change. Could you fix them directly in this PR, or create jira issues for later?

Staging: https://preview-mongodbnorareidy.gatsbyjs.io/php-library/DOCSP-36027/reference/

Why is this particular page empty?

Hi Jerome, this page isn't actually accessible from the docs site (other than by editing the URL directly) as it's just a drawer for all the API documentation and doesn't have any content. I just added it as the staging link since all the edited pages fall under this heading. Sorry for the confusion!

docs/reference/class/MongoDBBulkWriteResult.txt

docs/reference/write-result-classes.txt

jmikola · 2024-02-12T16:25:14Z

docs/reference/method/MongoDBClient__construct.txt

-MongoDB\\Client::__construct()
-==============================
+=============
+__construct()


I assume this was done to consolidate entries in the nav menu, but it means the page title itself is much more vague. Is there no way to preserve MongoDB\Client::__construct() here and only trim the navigation entry? One of my original suggestions (perhaps in Slack) was to modify the logic to generate menu content and apply some string manipulation. That would certainly require some tooling changes, but I think it's preferable to leaving the destination pages themselves without identifying titles.

As is, this page is going to show up in search results as "__construct() -- PHP Library Manual", which looks pretty bad.

I think we need some input from the docs platform team to see what's possible here. If there's not an immediate solution available, I think reducing the page titles to just the base class name and method (e.g. MongoDB\Client::__construct() -> Client::__construct()) would be the best compromise to allow meaningful page titles.

I reached out to docs platform and it seems like there is a way to do this! I'll change all the page titles back to the full namespace and just trim the navigation entry

I saw the Slack thread. Glad there's an existing solution for this, and thanks @schmalliso for the assist.

docs/reference/functions.txt

jmikola

Note: #1229 (comment) is still outstanding.

jmikola · 2024-02-13T19:37:06Z

docs/reference/class/MongoDBBulkWriteResult.txt

@@ -0,0 +1,39 @@
+.. _php-bulk-write-result:


Are these anchors still needed if the result classes now have their own pages? No need to clean this up now, as it can be addressed in a subsequent PR. It would entail both removing this and updating any links that refer to it (for all such redundant anchors).

If you'd prefer I remove the content from "Enumeration Classes", "Result Classes", etc (mentioned in this comment) then yes these anchors aren't necessary and I'll remove them. Otherwise, I'll keep the anchors if I make those landing pages clickable.

I replied in https://github.com/mongodb/mongo-php-library/pull/1229/files#r1489958124. I don't think these need to be clickable, but I also don't see anything in the docs that refers to these links so I'm not sure what they have to do with the visibility of the result and enumeration pages.

docs/reference/class/MongoDBChangeStream.txt

jmikola · 2024-02-13T19:40:45Z

docs/reference/class/MongoDBModelDatabaseInfoIterator.txt

+.. _php-model-database-info-iterator:
+
+==========================================
+MongoDB\\Model\\DatabaseInfoIterator Class


I can't say what's responsible for this, but I noticed some of the links under "Enumeration Classes" leave the UI in a strange state. For instance, https://preview-mongodbnorareidy.gatsbyjs.io/php-library/DOCSP-36027/reference/class/MongoDBModelDatabaseInfoIterator/ scrolls past all of the main content.

This could be due to the long titles. In this case, I'd be amenable to stripping the full namespace from the class page titles and preserving the fully qualified class name (FQCN) below in the Definition section.

So this can just be "DatabaseInfoIterator Class" if that helps with navigation. I think that would still be fine for SEO purposes.

Seems like shortening the title fixed the scrolling issue

This does still happen with some other pages: https://preview-mongodbnorareidy.gatsbyjs.io/php-library/DOCSP-36027/reference/method/MongoDBModelCollectionInfo-isCapped/

I imagine this isn't specific to PHPLIB, though, and is probably a more general issue with the docs theme. Perhaps worthy of a DOCSP ticket to be addressed later.

Ah, yeah I think this issue has come up before. I'll follow up with Docs platform.

jmikola · 2024-02-13T19:42:27Z

docs/reference/enumeration-classes.txt

+- :ref:`DatabaseInfo <php-model-database-info>`
+- :ref:`DatabaseInfoIterator <php-model-database-info-iterator>`
+- :ref:`IndexInfo <php-model-index-info>`
+- :ref:`IndexInfoIterator <php-model-index-info-iterator>`


Since the "Enumeration Classes" drawer is now clickable and expands (per https://github.com/mongodb/mongo-php-library/pull/1229/files#r1484800559), is this content even viewable anymore? I found no way to navigate to this page directly in the current staging deployment.

It's not viewable right now (other than by editing the URL or using the right/left arrow buttons at the bottom of each page). I can make it viewable, or leave as is and remove the content on this page

I think it makes sense to remove the content here. If possible, it'd be helpful to replace this with an RST comment explaining why it's omitted, as I don't think there'd be no indication from the docs sources alone that "Enumeration Classes" is not directly accessible.

jmikola · 2024-02-14T19:36:22Z

@norareidy: One last request on my end. Can we just eliminate "Enumeration Classes" and merge that with the "Result Classes" heading? I think the differentiation only made sense when there was an intermediary page showing all classes at once. Now that it's just a menu element and each class has its own page, I can't think of any reason to keep them separated.

Hopefully this also makes the docs configuration a bit simpler.

norareidy · 2024-02-15T15:49:26Z

@norareidy: One last request on my end. Can we just eliminate "Enumeration Classes" and merge that with the "Result Classes" heading? I think the differentiation only made sense when there was an intermediary page showing all classes at once. Now that it's just a menu element and each class has its own page, I can't think of any reason to keep them separated.

Hopefully this also makes the docs configuration a bit simpler.

Hi @jmikola, thanks for all the feedback on this PR! I merged "Enumeration Classes" into "Result Classes"; let me know if there are any other changes needed.

jmikola · 2024-02-21T14:55:41Z

@norareidy: Is this ready to merge on your end? If so, I can do so manually since the current repository rules are preventing you from doing so (see: #1231).

norareidy · 2024-02-21T17:59:50Z

@norareidy: Is this ready to merge on your end? If so, I can do so manually since the current repository rules are preventing you from doing so (see: #1231).

Yes it is! I was waiting for the checks to finish, but if you can bypass them that would be great.

Also consolidates result classes to a single section (cherry picked from commit 00d44d4)

norareidy marked this pull request as draft February 8, 2024 19:27

GromNaN reviewed Feb 9, 2024

View reviewed changes

mongoKart approved these changes Feb 9, 2024

View reviewed changes

jmikola reviewed Feb 12, 2024

View reviewed changes

norareidy marked this pull request as ready for review February 12, 2024 21:50

jmikola reviewed Feb 13, 2024

View reviewed changes

jmikola approved these changes Feb 16, 2024

View reviewed changes

norareidy added 16 commits February 21, 2024 15:14

DOCSP-36331: Shorten MongoDB\Client headings

a915365

DOCSP-36027: Shorten class headings

e4f0f02

restructuring to fix duplicate titles

b78928d

write result structure changes

cedba26

rest of structure changes

6aa9d91

fix methods sections

e560f31

gitignore

6260171

remove files

5477cf7

remove

b54410e

reorganizing files

0a7caf5

back to long titles

e8c6b29

enumeration titles

9849d4e

removing files

5a4bf99

fixing typos

eaedfe8

remove enumeration class

7b2c3de

shorten result classes

cff9310

jmikola force-pushed the DOCSP-36027-fix-class-headings branch from 19c9272 to cff9310 Compare February 21, 2024 20:14

jmikola merged commit 00d44d4 into mongodb:master Feb 21, 2024

norareidy added a commit to norareidy/mongo-php-library that referenced this pull request Feb 23, 2024

DOCSP-36027: Shorten class headings in nav (mongodb#1229)

a84eb33

Also consolidates result classes to a single section (cherry picked from commit 00d44d4)

jmikola mentioned this pull request Feb 26, 2024

DOCSP-36027: Shorten class headings backport (#1229) #1236

Merged

DOCSP-36027: Shorten class headings #1229

DOCSP-36027: Shorten class headings #1229

Uh oh!

Conversation

norareidy commented Feb 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GromNaN left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

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!

jmikola Feb 12, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

mongoKart left a comment

Choose a reason for hiding this comment

Uh oh!

norareidy commented Feb 12, 2024

Uh oh!

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!

Uh oh!

jmikola left a comment

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!

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!

jmikola commented Feb 14, 2024

Uh oh!

norareidy commented Feb 15, 2024

Uh oh!

jmikola commented Feb 21, 2024

Uh oh!

norareidy commented Feb 21, 2024

Uh oh!

Uh oh!

norareidy commented Feb 8, 2024 •

edited

Loading

GromNaN left a comment •

edited

Loading

jmikola Feb 12, 2024 •

edited

Loading