Improve "Online Manual" Operator for Tools and Options #37479

New Issue

Jonathan Williamson · 2013-11-15T20:14:43+01:00

2013-11-15 20:14:43 +01:00

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 [ http:*wiki.blender.org/index.php/Doc:2.6/Manual/Modeling/Meshes/Editing/Subdividing/Knife_Subdivide | 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.

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 [[ http:*wiki.blender.org/index.php/Doc:2.6/Manual/Modeling/Meshes/Editing/Subdividing/Knife_Subdivide | Modeling/Meshes/Editing/Subdividing/Knife_subdivide ](http:*wiki.blender.org/index.php/Doc:2.6/Manual/Modeling/Meshes). **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.

Jonathan Williamson commented

2013-11-15 20:14:43 +01:00

Changed status to: 'Open'

Jonathan Williamson commented

2013-11-15 20:14:43 +01:00

Added subscribers: @JonathanWilliamson, @brecht

Ken Beyer commented

2013-11-19 13:30:50 +01:00

Added subscriber: @katsbits

Ken Beyer commented

2013-11-19 13:30:50 +01:00

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?

Ken Beyer commented

2013-11-19 16:45:54 +01:00

Removed subscriber: @katsbits

Ken Beyer commented

2013-11-20 01:51:12 +01:00

Added subscriber: @katsbits

koil commented

2013-11-20 23:45:40 +01:00

Added subscriber: @koilz

koil commented

2013-11-20 23:45:40 +01:00

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.

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.

Jonathan Williamson commented

2013-11-22 20:35:44 +01:00

@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, is that correct? If so then this is something I can start doing.

Jonathan Williamson commented

2013-11-22 20:45:34 +01:00

@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.

Brecht Van Lommel commented

2013-11-22 20:47:55 +01:00

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 @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 ](http://developer.blender.org/D27?vs=56&id=63&whitespace=ignore-all#toc) using wildcards.

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 @koilz to update the shape key operators ([D27: wiki manual - shape keys](https://archive.blender.org/developer/D27)), 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](https://archive.blender.org/developer/D27) ](http://developer.blender.org/D27?vs=56&id=63&whitespace=ignore-all#toc) using wildcards.

Jonathan Williamson commented

2013-11-22 20:55:23 +01:00

@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.

Jonathan Williamson commented

2013-11-22 22:38:25 +01:00

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: blender/blender-addons@8da66b2936

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: blender/blender-addons@8da66b2936

Campbell Barton commented

2016-02-26 06:58:12 +01:00

Added subscriber: @ideasman42

Campbell Barton commented

2016-02-26 06:58:12 +01:00

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.

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.

Jonathan Williamson commented

2016-03-08 16:29:41 +01:00

Changed status from 'Open' to: 'Resolved'

Jonathan Williamson closed this issue

2016-03-08 16:29:41 +01:00

Jonathan Williamson self-assigned this 2016-03-08 16:29:41 +01:00

Jonathan Williamson commented

2016-03-08 16:29:41 +01:00

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

Sign in to join this conversation.

No Label

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Improve "Online Manual" Operator for Tools and Options #37479