Building Documentation#

The main GCC documentation uses Sphinx to generate pretty documentation from reStructuredText format. These are input for Manual pages format (make man), Info format (make info), HTML format (make html) and PDF format (make pdf).

Sphinx Install#

The ReST markups currently used by the documentation files are meant to be built with Sphinx version 5.3 or higher.

Most distributions are shipped with Sphinx, but its toolchain is fragile, and it is not uncommon that upgrading it or some other Python packages on your machine would cause the documentation build to break.

A way to avoid that is to use a different version than the one shipped with your distributions. In order to do so, it is recommended to install Sphinx inside a virtual environment, using virtualenv-3 or virtualenv, depending on how your distribution packaged Python 3.

$ virtualenv /tmp/venv
$ source /tmp/venv/bin/activate
$ pip install -r requirements.txt

Note the requirements.txt file is placed in gcc/doc folder and contains the following packages:

requirements.txt#
Sphinx>=5.3
furo
sphinx_copybutton

Then the virtualenv can be provided to the configure script --with-sphinx-build and will be used by the build system:

$ configure --with-sphinx-build=/tmp/venv/bin/sphinx-build

If you want to build the PDF documentation, you will need python3-Sphinx-latex sub-package.

Note

When building manual and info pages (built by default), the only dependency is Sphinx package and one can ignore other dependencies mentioned in requirements.txt.

Writing Documentation#

Adding new documentation can be as simple as:

  1. Add a new .rst file somewhere under a doc subfolder.

  2. Refer to it from the Sphinx main TOC tree in a index.rst file.

This is usually good enough for simple documentation (like the one you’re reading right now), but for larger documents it may be advisable to create a subdirectory (or use an existing one).

See the documentation for Sphinx and reStructuredText on what you can do with them. In particular, the Sphinx reStructuredText Primer is a good place to get started with reStructuredText. There are also some Sphinx specific markup constructs and Usefull RST cheatsheet.

Specific guidelines for the GCC documentation#

Here are some specific guidelines for the GCC documentation:

  • Please stick to this order of heading adornments:

    1. = with overline for document title:

    ==============
Document title
==============

    1. - for chapters:

    Chapter
-------

    1. * for sections:

    Section
*******

    1. ^ for subsections:

    Subsection
^^^^^^^^^^

    1. ~ for subsubsections:

    Subsubsection
~~~~~~~~~~~~~

    Although RST doesn’t mandate a specific order (“Rather than imposing a fixed number and order of section title adornment styles, the order enforced will be the order as encountered.”), having the higher levels the same overall makes it easier to follow the documents.

  • For inserting fixed width text blocks (for code examples, use case examples, etc.), use :: for anything that doesn’t really benefit from syntax highlighting, especially short snippets. Use .. code-block:: <language> for longer code blocks that benefit from highlighting. For a short snippet of code embedded in the text, use ``code snippet``.

  • For parts of documentation that needs to be written or enhanced, use .. todo:: directive (part of the official sphinx.ext.todo extension). In development mode, all items are listed at the very end of the documentation for easier navigation.

GCC-specific directives and roles#

GCC uses its own extension (gcc_sphinx.py) that defined various directives. For the complete list of target-specific attributes, please take a look at the extension definition:

Directive

Description

gcc-attr

Generic GCC attribute

fn-attr

Function attribute

var-attr

Variable attribute

type-attr

Type attribute

enum-attr

Enumeral attribute

label-attr

Label attribute

$target-fn-attr

Target-specific function attribute (e.g. .. x86-fn-attr:: interrupt)

$target-var-attr

Target-specific variable attribute

$target-type-attr

Target-specific type attribute

gcc-param

GCC parameter directive, (e.g. .. gcc-param: inline-unit-growth)

Apart from the directives, we also define various inline roles:

Role

Description

:P:`$num`

Link to WG21 - The C++ Standards Committee (e.g. :P:`2003`)

:PR:`$num`

Link to GCC bugzilla entry

:openmp:`$version`

Link to OpenMP documentation version $version (e.g. :openmp:`4.5`)

:openacc:`$version`

Link to OpenACC documentation version $version

|gcc_version|

Version of the documentation (e.g. 13.0.1, taken from BASE-VER)

|needs_sphinx|

Minimal required Sphinx version (e.g. 5.3, taken from baseconf.py)

|bugurl|

URL to bugzilla instance (e.g. https://gcc.gnu.org/bugs/)

|package_version|

Package version (e.g. (GCC))

|gol|

Line break used for PDF version

|nbsp|

Non-breaking space character

Miscellaneous Documentation#

In addition to the formal documentation that is installed by GCC, there are several other text files in the gcc subdirectory with miscellaneous documentation:

ABOUT-GCC-NLS

Notes on GCC’s Native Language Support.

Todo

this should be part of this manual rather than a separate file

ABOUT-NLS

Notes on the Free Translation Project.

COPYING

The GNU General Public License, Versions 2 and 3.

COPYING.LIB COPYING3.LIB

The GNU Lesser General Public License, Versions 2.1 and 3.

*ChangeLog* */ChangeLog*

Change log files for various parts of GCC.

LANGUAGES

Details of a few changes to the GCC front-end interface.

Todo

the information in this file should be part of general documentation of the front-end interface in this manual.

ONEWS

Information about new features in old versions of GCC. (For recent versions, the information is on the GCC web site.)

README.Portability

Information about portability issues when writing code in GCC.

Todo

why isn’t this part of this manual or of the GCC Coding Conventions?

Todo

document such files in subdirectories, at least config, c, cp, objc, testsuite.