Cross-Reference

This section shows how to cross-reference documentation or code.

Documentation References

Ref Titles

The autosectionlabel Sphinx extension automatically internally adds labels to headings. So no need to explicitly manually add labels.

Examples

:ref:`PlantUML`

E.g. PlantUML

1
2
3
======================================================
PlantUML
======================================================

Ref Labels

If we want to reference something that isn’t a heading or section then we can add our own labels manually. Labels can be added anywhere. And these can be referenced from elsewhere.

Add label to target location

1
2
3
4
5
6
.. _plantuml-label:


======================================================
PlantUML
======================================================

Reference the label

:ref:`plantuml-label`

E.g. PlantUML

Code References

We already have the code references from Doxygen already.

To reference them, we use Breathe’s rich set of directives:

  • doxygenstruct

  • doxygenfunction

  • doxygenclass

  • doxygendefine

  • doxygenenum

  • doxygenenumvalue

  • doxygenfile

  • doxygengroup

  • doxygenindex

  • doxygennamespace

  • doxygeninterface

  • doxygentypedef

  • doxygenunion

  • doxygenvariable

Examples are given here for our HelloWorld C source for:

  • doxygenstruct

  • doxygenfunction

Structure

Tip

See https://breathe.readthedocs.io/en/latest/struct.html

.. doxygenstruct:: Hellomessage
:members:

gives

struct Hellomessage

A dummy struct

Public Members

char message[20]

message to use to say hello

for this structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
/** 
 *  @file hello-world.h
 */


#pragma once

/**
 * A dummy struct
 */
struct Hellomessage {
  /**
  * message to use to say hello
  */
	char message [20];
} hellomessage;

Function

Tip

See https://breathe.readthedocs.io/en/latest/function.html

.. doxygenfunction:: HelloWorld

gives

int HelloWorld(void)

brief explanation of hello-world.c

Return

1

for this function

1
2
3
4
5
/**
 * @brief	brief explanation of hello-world.c
 * @return 1
 */
int HelloWorld(void);