Hello, I am currently creating some new documentation here: https://github.com/apache/arrow/pull/13859, and would like to enhance other documentation over time, so I would like to figure out best practices. However, some areas lack standardization in the documentation.
In particular, classes are referred to in multiple ways. This is making it difficult to make new documentation in a semi-standardized manner, and I would like to see about standardizing this. In https://arrow.apache.org/docs/cpp/compute.html, a namespace is used in Sphinx to be able to use class directives (which create links to relevant locations in API documentation) in short form. Most functions are referred to using orange text, and classes are referred to in orange text after their introduction (a style similar to wikis, in which something has a hyperlink the first time, then is plaintext afterwards.) In https://arrow.apache.org/docs/cpp/arrays.html, there is a mix, where terms such as "Arrow array" are used alongside class directives that use the full namespace qualifiers. In https://arrow.apache.org/docs/cpp/dataset.html, when a class is mentioned directly, it has its full namespace included in a class directive each time. I personally like the idea of using namespace directives in Sphinx to keep things less cluttered and easier to write, then using the class directive each time so links are always available. As for functions, I'd like to keep them in "orange text," unless they are unconnected to a class in use in the article -- if they are, I would like to use directives there, as well. What would all of you prefer as a standard? I would want to use the determined direction in the documentation I am creating, and would want to propagate it through existing articles over time. Kae Suarez
