Improved Navigation of API Documentation

MErikReedAugusta — Thu, 04 Apr 2024 22:05:16 GMT

Today, I found myself down the rabbit hole trying to decipher the documentation for Feature, FeatureLayer, and FeatureLayerCollection in the API for Python. Navigating between each of the three is workable, because I have bookmarks on the left to take me right to the top of each (marked A in the screenshot).

The Problem:

All of the contents of a given module share the same page, without break. The bookmarks will take you to the header of the class, but the headers for properties & methods below that are a bit of a mess.

Each of the properties & methods (marked B in the screenshot) are immediately followed by their description and sometimes a lengthy example. Some of those examples are actually longer than the screen area, to boot, so you can be looking at the middle of an example and not even know which method it or class it belongs to.

All this together means that it's easy to get lost digging through the properties and constantly be scrolling frantically up & down to understand the context of what you're reading.

The Solution(s):

Option 1: Each of these classes gets their own subpage. You can't scroll from Feature to FeatureLayer in one continuous go; you'll have to click somewhere to navigate to the page for FeatureLayer if you want to read it.

Option 2: Add another level of depth to the navigation that lists the heading level used by B; i.e., all the properties & methods. This is what the horribly-sketched arrows at C are indicating.

Option 3: Add a table-of-contents sort of section to the top of every class that just lists the property or function, but without any of the descriptions or examples. This can then hyperlink to lower on the page where you can read more details.

Personally, my preference is Option 2, but I could live with any of these three. But the current layout is unnecessarily abstruse, especially to someone trying to look something up for the first time, without knowing what the property is called. And frankly, it's equally terrible for someone who knows more or less what they're looking for, but needs to refresh themselves on some implementation detail.

Re: Improved Navigation of API Documentation

A_Schwab — Fri, 05 Apr 2024 07:56:01 GMT

Adding my +1 to this. I have the same frustrations using the API docs.

Re: Improved Navigation of API Documentation

Raul — Tue, 16 Apr 2024 20:47:00 GMT

We've been asking for better documentation of that API since it's inception :')

I wish it looked more like the Javascript API documentation, but you get a +1 from me!

Re: Improved Navigation of API Documentation

RichardHowe — Thu, 20 Mar 2025 11:28:47 GMT

Yes please!

idea Improved Navigation of API Documentation in ArcGIS API for Python Ideas

Improved Navigation of API Documentation

Re: Improved Navigation of API Documentation

Re: Improved Navigation of API Documentation

Re: Improved Navigation of API Documentation