Comparison of GCC docs in Texinfo and Sphinx#

HTML output#

Formatting#

Sphinx provides left menu navigation and side bar navigation (for subsections) on a page. Moreover, it’s using a richer CSS formats including the code highlighting for code snippets, bash sessions or a JSON output.

Texinfo version:

Sphinx version (see Profiling and Test Coverage in Freestanding Environments):

Links#

Entire manual can be easily visited with cross-references for thinks like options, attributes, etc.

Texinfo version:

Sphinx version (see e.g. -O2):

Built-in Search Engine#

Sphinx provides built-in search enging for a fast navigation:

Link location#

HTML links for options are misplaced by Texinfo:

While it’s precise for Sphinx (e.g. -fdefer-pop):

Cross-manual references#

Sphinx (using Intersphinx extension) provides an elagant way how to cross reference other manuals): (e.g. :ref:`gcc:amd-gcn-options` AMD GCN Options)

Function documentation#

Sphinx provides very rich directives when documenting a function, it’s arguments, return value, etc.

.. c:function:: PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

:param type: description of the first parameter.
:param nitems: description of the second parameter.
:returns: a result.
:retval NULL: under some conditions.
:retval NULL: under some other conditions as well.

which results in:

PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)#

Parameters:

type – description of the first parameter.
nitems – description of the second parameter.

Returns:

a result.

Return values:

NULL – under some conditions.
NULL – under some other conditions as well.

PDF output#

Cross-manual references#

Again, PDF version contains many references which are handy with preview feature:

Texinfo version:

Sphinx version:

Code highlighting#

Again, the PDF version provides built-in syntax highlighting provided by Pygments package: