Page MenuHome

Improve "Online Manual" Operator for Tools and Options
Closed, ResolvedPublic

Description

The current method to view documentation for specific tools is a bit worthless. There's no explicit lookup happening to direct the user to the exact documentation page, and so generally the user is sent to a generic page and then must find the specific tool/option documentation from there. For anyone that's not familiar with the documentation this leaves them at a lost, unable to find what they need. Effectively making the Online Documentation operator worthless.

For Example
The Knife mesh tool documentation goes to Modeling/Meshes, when it should go to Modeling/Meshes/Editing/Subdividing/Knife_subdivide.

Proposal
Explicitly set the URL for all operators. This gives more burden to the developers of said operator, but ensures accurate documentation links for that operator. This is also something that junior developers (such as myself) can easily maintain.

Details

Type
Design

Event Timeline

Aren't tools and operators given unique URL identifiers by default or are they largely generic (how many link to the same page when they should link to specific information)? Are the numbers known?

The operators and properties have a python pointer.
bpy.ops.mesh.knife_tool
So the doc id is 'bpy.ops.mesh.knife_tool'.

http://developer.blender.org/diffusion/BA/browse/master/modules/rna_wiki_reference.py

So here:
line 303: ("bpy.ops.mesh.*", "Modeling/Meshes"),
You add:
line 303: ("bpy.ops.mesh.*", "Modeling/Meshes"),
line 304: ("bpy.ops.mesh.knife_tool", "Modeling/Meshes/Editing/Subdividing/Knife_Subdivide"),

303 is generic, 304 is specific.

'(how many link to the same page when they should link to specific information)? Are the numbers known?'

Most at the moment are generic, most mesh operators go to the Modeling/Meshes page without a specific link.

@koil (koilz), so it seems to me that we just need to go in and update the rna_wiki_reference.py for each tool that needs a specific entry? Which is most. @Brecht Van Lommel (brecht), is that correct? If so then this is something I can start doing.

@koil (koilz), it should be noted that you actually need to reverse line 303 and 304, or else knife_tool will satisfy line 303 first and still just go to Modeling/Meshes.

Yup, it seems there is actually a list but it's in the addons repository so missed that at first. I actually already committed a patch by @koil (koilz) to update the shape key operators (D27: wiki manual - shape keys), and I'm happy to commit more.

This is something that's fairly easy for people to start contributing to. Note how using * wildcards you can avoid adding entries for each individual operator, see how the diff was simplified in D27 using wildcards.

@Brecht Van Lommel (brecht) okay cool. Then if it's alright I'll start working on manual entires for the mesh operators. I agree wildcards are good, but for somethings they've been too over zealous. For example, a single wild card for all mesh operators is silly :) But for things like each of the various Shapekey operators, it makes good sense.

Some progress on this one. I have begun updating the manual references to point to the correct tool, rather than being general.

First up, the 3D View toolbar mesh operators: rBA8da66b293675b51d1e2065b442f2a70ce93a4b58

Going over User Interface tasks and there's quite a lot of vague "area needs improvement" tasks.

These just stay open and don't have clear conclusion... since this task was opened we've updated and added manual links, yet many more could be added too.

I would like to see tasks like this have a clear scope (list exactly what needs doing), or be closed.

Good call @Campbell Barton (campbellbarton). I'll close and create new, more specific ones as they come up