Include Description in the Search Documentation?

bentraje

Hi,

Is it possible to include the description in the search documentation?

Case in point: "Bounding Box"

It doesn't return the GetRad method that outputs the actual bounding box. It does return c4d.BaseObject but the unassuming wouldn't know there is such method.

ferdinand

Hello @bentraje,

Thank you for reaching out to us. Could you elaborate what you mean by description in this context?

For clarification: Description has a reserved meaning in the Cinema 4D API, and I assume you are somewhat aware of that, but at least I cannot connect the dots how you mean that.

All C4DAtom instances have a description (some are empty though). A description is primarily represented by *.res, *.h and *.str files on disk, e.g., this is the resource file for the cube object.

CONTAINER Ocube
{
	NAME Ocube;
	INCLUDE Obase;

	GROUP ID_OBJECTPROPERTIES
	{
		GROUP
		{
			VECTOR	PRIM_CUBE_LEN    { MIN 0 0 0; UNIT METER; CUSTOMGUI SUBDESCRIPTION;  }
			LONG    PRIM_CUBE_SUBX   { MIN 1; MAX 1000; CUSTOMGUI LONGSLIDER; STEP 1; MINSLIDER 1; MAXSLIDER 20; }
			LONG    PRIM_CUBE_SUBY   { MIN 1; MAX 1000; CUSTOMGUI LONGSLIDER; STEP 1; MINSLIDER 1; MAXSLIDER 20; }
			LONG    PRIM_CUBE_SUBZ   { MIN 1; MAX 1000; CUSTOMGUI LONGSLIDER; STEP 1; MINSLIDER 1; MAXSLIDER 20; }
			SEPARATOR { }
			BOOL	PRIM_CUBE_SEP    { }
			BOOL	PRIM_CUBE_DOFILLET { }
			REAL    PRIM_CUBE_FRAD	 { PARENTID PRIM_CUBE_DOFILLET; MIN 0; UNIT METER; CUSTOMGUI REALSLIDER; STEP 1; MINSLIDER 0; MAXSLIDER 20; }
			LONG    PRIM_CUBE_SUBF   { PARENTID PRIM_CUBE_DOFILLET; MIN 1; MAX 1000; CUSTOMGUI LONGSLIDER; STEP 1; MINSLIDER 1; MAXSLIDER 10; }
		}				
	}
}

In the Python API, descriptions are represented by c4d.Description instances, which are accessible for every atom via C4DAtom.GetDescription. Such description then contains the content of the files mentioned above. In the Python documentation descriptions are documented, you can find the Ocube description for example here.

BaseObject.GetRad() is however not part of descriptions, as this information is simply not stored there. Dcoumented is the base description for all objects, Obase but this just contains all the entry points for accessing the transform(s) of an object among other things.

So, could you please clarify what you mean? I am not saying that this might not be a reasonable request, I am just struggling a bit with what you want to be done here.

But the bounding box radius of an object cannot be found in its description, and while everything is possible with enough dedication, I do not see the direct benfit of exposing this value as a description parameter.

Cheers,
Ferdinand

bentraje

@ferdinand

No worries. My fault for not specifying.
Here's what I meant by "description" in a layman way. huehue

GetRad has a description of "This is the bounding box radius of the object". But it doesn't get return as a search result of "bounding box" in search documentation.

Of course, it's not necessarily a deal breaker since if you search "bounding box" in the forum and you'll see GetRad gets mentioned.
But it makes a "secondary" documentation compared to the forum.

There's several cases like that where it should be a simple search in the documentation but it gets tricky.

ferdinand

Hello @bentraje,

ah, okay, I get what you mean, you want us to spice up the search index with related concepts and synonyms, so that you can search for "bounding box" and it will spit out these two methods or that you search for "geometry" and it will spit out c4d.PolygonObject for example.

Yeah, we have already talked about this internally and more sematic relations to things would be indeed helpful, both in C++ and Python. And Sphinx, i.e., our Python platform is better with this than Doxygen, our C++ platform. When you search for bounding box radius it will actually spit out c4d.BaseObject as the third hit (Doxygen would not do that).

It is possible to spice up the indices of Sphinx manually, but apart from technical problems related to Sphinx which are all more or less solvable with enough time, constructing search engine indices is no trivial task. You can of course ingest everything which is not tied to the ground into the index, but this will have the result of bloated search results as already to be experienced with Sphinx and the large amounts of junk its full-text search indexing produces.

To have a high recall and precision in search results, a high DCG - or less technical: have all and only the relevant stuff in search results - you usually must get much more sophisticated with your data than either Sphinx or Doxygen are. From an external perspective this might seem trivial - just index this, just index that - but our document space is simply too large to do this by hand directly on a database/SE level. To solve this truly we would have to migrate our documentation data to more complex data structures which make this manual indexing a. easier and b. partially automated.

The naive approach, simply tokenizing all text, then removing stop words, and then ingesting them in all contexts will yield very bloated search results. So, all I can say here is: We are aware and we also want a better search, but it is currently undecided which technical route we will take.

Cheers,
Ferdinand

bentraje

@ferdinand

Uhm. It's not as complicated as that.
I mean it is complicated per se but there are already existing solutions.
Check "Sphinx Search Extension". There are several.
Pip install it and just insert it into the conf.py file.

Also, it's not really as spicing it up per se.
I mean it is but not really.

It's just adding a sub paragraph section.
The maxon redshift documentation is already doing it.
And even if you are using sphinx implementation, it's also existing.
Blender documentation is built using sphinx.