Old Python Documentation

General Discussion
1

Hello,

It would be so awesome if I could use the old documentation! If someone could put that back online it would be great.

I am not the most versed programmer, but I cannot find any of the simple functions of classes in the new documentation, like getPos(), setScale(), etc.

Thanks,
Gary

2

We go here:
panda3d.org/reference/python/annotated.php

Type into the little box at the top right that says “search” something like “getPos”, and wait for it to fetch results.

Click on first “getPos” result to expand it.
Click on “panda3d::core::NodePath.getPos()” - assuming that’s what you want.

We arrive here:
panda3d.org/reference/python … 1873752cbb

Of course, I am a newb, so maybe I misunderstood you.

3

The old API reference is still at:
panda3d.org/apiref.php?page=classes
It will soon be a redirect for the new doxygen reference, though.

4

Perhaps a bigger question is in what way are you failing to find these method definitions on the new documentation? They seem perfectly obvious to me on the various class pages. What pages are you coming to where you expect to see them and they are not there?

David

5

It seems to me that OP’s problem is that the original list of methods lists getPos:

panda3d.org/apiref.php?page=methods

But the new one doesn’t:

panda3d.org/reference/python … hp#index_g

Instead it lists “pos” as a variable:

panda3d.org/reference/python … hp#index_p

Also cross-referencing doesn’t seem to work very well, this is what we get now for the pos:

For getPos we used to get:

6

What do you mean? I see getPos() listed in the index_g list you link to:

getPos() : AnimChannel< ACScalarSwitchType > , DriveInterface , Trackball , TrackerNode , OnscreenText , NodePath , PolylightNode , OdeContactGeom , AnimChannel< ACMatrixSwitchType > , TransformState , NodePath

And see, it does have a sensible cross-reference. The “pos” variable is a different list, and references Python objects that actually do have a “pos” variable.

David

7

Oh sorry, I must be blind. I didn’t found it for some reason, maybe I had my search on match case or something. Because it has happened to me that I don’t find something I didn’t double check, for example, here:

panda3d.org/reference/cxx/annotated.php

I picked a class at random and didn’t find it. Where is DynamicTextFont? It certainly was in the old api ref. (I hope it doesn’t turn out that it’s actually there again)

EDIT: It is in the Python side though, must be a c++ api ref problem.

8

Hmm, you’re right, that class is missing from the C++ documentation. I wonder why?

9

Well, rdb says doxygen gets easily confused with macros. There are other problems with the reference, like class descriptions missing on the C++ side, we’ll work on it.

10

Hmmm. Maybe I forgot how to navigate the docs after taking a month off, seem to remember it being easier before, but can’t remember why.

Never knew about the methods page though, sweet indeed!

11

hotmonke, I think you’re not alone in feeling like the older docs were easier to navigate for some reason. I’ve been wondering about this myself, I’ve become completely helpless with the new Reference and I couldn’t figure out why. But I have some theories:

  1. The Search bar is way more powerful than it looks, so until I read this thread I didn’t even notice it. :slight_smile:

  2. The old reference had a 2D layout (3 columns) instead of a single column. There are many many classes, so the compact 2D layout can feel a little more manageable. The tradeoff though is that the new design can include descriptions for classes, which is helpful.

  3. the green-on-blue text is harder on the eyes in the newer layout

  4. more importantly, there are some confusing things going on with Classes and Packages views. The reference for some very commonly used classes can be hard to find unless you really know what you’re doing. For example:

Example 1: under Class List, Actor gives you this:
panda3d.org/reference/python … 1Actor.php

I’m not really sure what that is, but what I wanted to look up is actually only listed in Packages, as actor.Actor:
panda3d.org/reference/python … 1Actor.php

And is the same as the ref for “Actor” in the 1.6.2 reference.

“Classes->Class List” suggests that you should be able to get to any class in a flat list, while “Packages” is the way you’d get to that class via the package it’s in - but here actor.Actor is only accessible through one of those paths.

Example 2: Vector math. The ref for a 3-component vector, for example, used to be accessible under “Vec3”. Now, however, it’s only listed under “LVector3f,” which I imagine is maybe the internal C++ class name? There are several problems with this:

  1. the class name you’d use in Python is Vec3, not LVector3f or LBaseVec3f, and it’s not evident that these are the same thing.
  2. it’s hard to know that LVector3f is the thing you should look for. Searching for “Vec” or “Vector” does not return it, because it begins with “L” and the search box only matches strings at the beginning of class names. Using the web browser’s Find function on the Class List page gets there eventually, but there are many instances of the word “vector” on the page before so the user may give up.
  3. if you do figure out that LVector3f is the right class, you may try to use it (e.g. p=LVector3f(0,0,0)) which makes harder-to-read code and anyway throws an error.

IMHO the reference presents a very real design problem which is not easy to solve, but which is worth thinking about. Here are some observations …

  1. A good reference is one of the most important things
  2. Panda is really big and complex.
  3. Panda has users who are ok at programming but are not veteran software engineers.
  4. There’s a lot in the reference you rarely need, and a few things you always need - it’s difficult to get to the important things. The reference also includes things most people will never need and shouldn’t use, because they’re internal Disney things.
  5. If you can’t remember the exact name of the class you’re looking for, it’s not not always easy to find it either by browsing or by searching
  6. Some of the most important things in Panda are fake globals, like “render,” “camera”, “base”, etc. It’s not evident that those can be found under “ShowBase”, and they don’t have any description once you do find them.

But without getting into too many other gory details the major issue to me is just the problem of finding the one relevant piece of information in a large set. Right now it’s a bit overwhelming.

One thing which might help is to design ways to lead the user to more commonly-needed results first before more obscure ones. For example, when looking up getPos(), perhaps NodePath.getPos() should come up before DriveInterface.getPos()?

Or, what about a “Basic” and “Extended” version of the reference? The “Basic” version could be an edited selection of the most commonly used classes, and perhaps even the most commonly used functions within important classes.

One other idea - would it be possible to let users on the site post commentary and code snippets on the reference pages, like in the PHP reference pages?

[/list]

12

Hm… the Actor thing does look like a bug in doxygen, as it appears to think that these functions are at module-level rather than being methods of the class. This may be caused by the fact that there are classes inside the Actor class.

I’ll fix the LVecBase3f > VBase3 thing, I simply forgot to remap these special classes.