git.net

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Language-independent and cross-language docs


Hi,

In the following PR discussion it was mentioned that we currently lack a
central documentation system for cross-language topics:
https://github.com/apache/arrow/pull/1575#issuecomment-364062240

Sphinx looks like a reasonable contender for that purpose.  For that who
don't know it, Sphinx is a documentation system initially developed for
the Python language, which quickly became widely-used amongst Python
projects, and is now being used by non-Python projects as well.  For
example, the LLVM docs (https://llvm.org/docs/) and even the Linux
kernel online docs are now written using Sphinx
(https://www.kernel.org/doc/html/latest/index.html).

Sphinx uses reStructuredText (a.k.a "reST") as its basic markup
language, but with many extensions.  It allows for structured
documentation with extensive cross-referencing (even between independent
Sphinx sites, using the "intersphinx" extension).

The questions here are:

- Should we do this at all (i.e. build up a central documentation system)?

- Should we use Sphinx for it?

- To which extent our current docs should be migrated to Sphinx (apart
from the Python docs, which already use Sphinx)?  For example, should
the specs (currently standalone pages written in Markdown) be migrated
to Sphinx for better cross-referencing and navigation?  What about the
C++ tutorial pages?  etc.

- Should we preferably have a single Sphinx doctree, or several
independent per-topic / per-language doctrees?

Regards

Antoine.