I do not know about the namespace issue in the API reference, but when focusing on the User's Guide and Getting Started sections, we can announce at the top of the page what namespace is relevant. I personally recommend using only the arrow namespace for ease in documentation and being more manual with the ones after that (e.g., using compute::CallFunction() instead of CallFunction() or arrow::compute::CallFunction()). This way, users will know that we're generally using Arrow's namespace, and any namespace is contained therein and important to keep an eye on.
As for "always linking," sure! I can do that, and we can see how it looks in the PR I'm working on. Thanks for the feedback, I'll be back in a while with some real-world results. Kae Suarez On Tue, Aug 30, 2022 at 1:57 PM David Li <lidav...@apache.org> wrote: > "Always linking" sounds reasonable to me. It also makes the decision > easier, for both author and reviewer. > > I feel like there must be some way to configure Breathe or Sphinx to show > the namespace in Antoine's example, but I don't see it… > > On Tue, Aug 30, 2022, at 08:52, Antoine Pitrou wrote: > > Hello Kae, > > > > Le 29/08/2022 à 19:28, Kae Suarez a écrit : > >> > >> 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. > > > > I would agree with this. As for the namespace, though, one question is > > how the user might derive in which namespace a class lives? > > > > For example, > > > https://arrow.apache.org/docs/cpp/api/dataset.html#_CPPv4N5arrow7dataset7DatasetE > > doesn't mention that the class lives in the arrow::dataset namespace. > > > > > > > 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. > > > > I would rather see functions/methods hyperlinked as well, as much as > > possible. > > > > Regards > > > > Antoine. >
