open3d::docstring::FunctionDoc Class Reference

#include <docstring.h>

Public Member Functions
	FunctionDoc (const std::string &pybind_doc)
std::string	ToGoogleDocString () const
	Generate Google style python docstring. More...

Static Public Member Functions
static std::string	NamespaceFix (const std::string &s)
	Apply fixes to namespace, e.g. "::" to "." for python. More...

Data Fields
std::string	name_ = ""
std::vector< ArgumentDoc >	argument_docs_
ArgumentDoc	return_doc_
std::string	summary_ = ""
std::string	body_ = ""

Protected Member Functions
void	ParseFunctionName ()
	Parse the function name from docstring. More...
void	ParseSummary ()
	Parse the function "summary" docstring received from pybind. More...
void	ParseArguments ()
	Parse ArgumentDoc for each argument. More...
void	ParseReturn ()
	Parse function return. More...

Static Protected Member Functions
static std::vector< std::string >	GetArgumentTokens (const std::string &pybind_doc)
static ArgumentDoc	ParseArgumentToken (const std::string &argument_token)
	Parse individual argument token and returns a ArgumentDoc. More...
static std::string	StringCleanAll (std::string &s, const std::string &white_space=" \")
	Runs all string cleanup functions. More...

Protected Attributes
std::string	pybind_doc_ = ""

Detailed Description

This class is designed to parse docstrings generated by pybind11 and convert to Python friendly Google-style docstring with the flexibility of adding additional docstrings manually.

The automated part includes:

1. Function name
2. Argument
   • Name
   • Type
   • Default value
3. Return type
4. Brief "summary" docstring received from pybind Optionally, the user can inject additional docstrings to the class.

This approach was chosen in favor of writting docstring in Python files for two reasons 1) We don't need to create additional (pure) Python wrapper functions, 2) The type information generated by pybind is preserved.

However, this also comes with a drawback: FunctionDoc rely on docstrings generated by pybind11, which is subject to change. So if a new version of pybind11 changes the format of docstring, this class needs to be updated accordingly. Another alternative approach is to modify pybind11 directly, although it makes some of the parsing part simpler, it could be much harder to maintain to keep track of the upstream pybind11.

Example usage:

std::string doc = R"(foo(arg0: int, arg1: float = 1.0) -> open3d.bar)";
FunctionDoc fd(doc);
fd.InjectArgumentDocBody("arg0", "The arg0 is an important argument.");
std::cout << fd.ToGoogleDocString();

Constructor & Destructor Documentation

FunctionDoc()

open3d::docstring::FunctionDoc::FunctionDoc

(

const std::string &

pybind_doc

)

Member Function Documentation

GetArgumentTokens()

std::vector< std::string > open3d::docstring::FunctionDoc::GetArgumentTokens ( const std::string &  pybind_doc )

staticprotected

Split docstring to argument tokens E.g. "cylinder_radius: float = 1.0", "cylinder_radius: float"

NamespaceFix()

std::string open3d::docstring::FunctionDoc::NamespaceFix ( const std::string &  s )

static

Apply fixes to namespace, e.g. "::" to "." for python.

ParseArguments()

void open3d::docstring::FunctionDoc::ParseArguments ( )

protected

Parse ArgumentDoc for each argument.

ParseArgumentToken()

ArgumentDoc open3d::docstring::FunctionDoc::ParseArgumentToken ( const std::string &  argument_token )

staticprotected

Parse individual argument token and returns a ArgumentDoc.

ParseFunctionName()

void open3d::docstring::FunctionDoc::ParseFunctionName ( )

protected

Parse the function name from docstring.

ParseReturn()

void open3d::docstring::FunctionDoc::ParseReturn ( )

protected

Parse function return.

ParseSummary()

void open3d::docstring::FunctionDoc::ParseSummary ( )

protected

Parse the function "summary" docstring received from pybind.

StringCleanAll()

std::string open3d::docstring::FunctionDoc::StringCleanAll ( std::string &  s, const std::string &  white_space = " \t\n"  )

staticprotected

Runs all string cleanup functions.

ToGoogleDocString()

std::string open3d::docstring::FunctionDoc::ToGoogleDocString

(

)

const

Generate Google style python docstring.

Field Documentation

argument_docs_

std::vector<ArgumentDoc> open3d::docstring::FunctionDoc::argument_docs_

body_

std::string open3d::docstring::FunctionDoc::body_ = ""

name_

std::string open3d::docstring::FunctionDoc::name_ = ""

pybind_doc_

std::string open3d::docstring::FunctionDoc::pybind_doc_ = ""

protected

return_doc_

ArgumentDoc open3d::docstring::FunctionDoc::return_doc_

summary_

std::string open3d::docstring::FunctionDoc::summary_ = ""

---

The documentation for this class was generated from the following files:

• /home/travis/build/intel-isl/Open3D/src/pybind/docstring.h
• /home/travis/build/intel-isl/Open3D/src/pybind/docstring.cpp