doc: prepare for improving doc API linking

Linking to API material requires knowing the pecularities of how doxygen, sphinx, and breathe work. In an attempt to hide some of this we're preparing the current docs to allow use of configuration defaults that will let us more simply use a default role that will hunt for a reference target in the various domains that are available by using a default "role" of "all". This will let us use the simple notation `functionname` or `typename` without fully specifying the reference as :c:func:`functionname`. This patch cleans up exising docs that were (incorrectly) using single backtics where double backtics should have been used, and also found some typos (such as a space between the role name and the reference, such as :file: `filename`, and a missing colon such as c:func:`functionname`) This is a start to address issue #14313 Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
zephyrproject-rtos · Mar 15, 2019 · 6000a62 · 6000a62
1 parent a514898
commit 6000a62
Show file tree

Hide file tree

Showing 30 changed files with 72 additions and 57 deletions.
diff --git a/boards/arm/mec2016evb_assy6797/doc/index.rst b/boards/arm/mec2016evb_assy6797/doc/index.rst
@@ -62,8 +62,7 @@ features:
 Other hardware features are not currently supported by Zephyr (at the moment)
 
 The default configuration can be found in the Kconfig file:
-
-        ``boards/arm/mec2016evb_assy6797/mec2016evb_assy6797_defconfig``
+``boards/arm/mec2016evb_assy6797/mec2016evb_assy6797_defconfig``
 
 
 Connections and IOs
@@ -178,7 +177,7 @@ Flashing
    - Stop bits: 1
 
 #. Connect the MEC2016EVB_ASSY_6797 board to your host computer using the
-   UART0 port. Then build :ref: `hello_world` application. It is important
+   UART0 port. Then build :ref:`hello_world` application. It is important
    to generate a binary with a new load address, for example do the following::
 
         ${OBJCOPY} --change-addresses -0xb0000 -O binary -S ${in_elf} ${out_bin}

diff --git a/boards/arm/nrf52832_mdk/doc/index.rst b/boards/arm/nrf52832_mdk/doc/index.rst
@@ -14,7 +14,7 @@ The kit gives access to 24 I/Os and interfaces via headers and has a
 RGB LED which is user-programmable. It also has a 2.4GHz chip antenna
 onboard which is quite convenient to develop IoT wireless applications.
 
-See `nRF52832-mdk website_` for more information about the development
+See `nRF52832-mdk website`_ for more information about the development
 board and `nRF52832 website`_ for the official reference on the IC itself.
 
 References

diff --git a/boards/arm/nrf52840_mdk/doc/index.rst b/boards/arm/nrf52840_mdk/doc/index.rst
@@ -19,7 +19,7 @@ ports: one for DAPLink interface and one for nRF52840 USB device controller.
 The kit also features ultra-low power 64-Mb QSPI FLASH memory, programmable
 user button, RGB LED, up to 24 GPIOs, antenna selection for custom applications.
 
-See `nRF52840-mdk website_` for more information about the development
+See `nRF52840-mdk website`_ for more information about the development
 board and `nRF52840 website`_ for the official reference on the IC itself.
 
 References

diff --git a/boards/arm/nrf52840_pca10059/doc/index.rst b/boards/arm/nrf52840_pca10059/doc/index.rst
@@ -148,8 +148,8 @@ It is possible to use the nRF5 bootloader alongside MCUBoot. To do so,
 program the board with MCUBoot as a Zephyr application, following
 the steps above. Then, prepare to compile an application with MCUBoot support.
 
-Select :option: `CONFIG_BOOTLOADER_MCUBOOT`, under "Boot options" and set
-:option: `CONFIG_TEXT_SECTION_OFFSET` under "Build and Link features",
+Select :option:`CONFIG_BOOTLOADER_MCUBOOT`, under "Boot options" and set
+:option:`CONFIG_TEXT_SECTION_OFFSET` under "Build and Link features",
 "Linker options" to 0x200 to ensure the code is offset to account for MCUboot
 firmware image metadata.
 

diff --git a/boards/arm/nrf52840_pca10090/doc/index.rst b/boards/arm/nrf52840_pca10090/doc/index.rst
@@ -100,7 +100,7 @@ First, run your favorite terminal program to listen for output.
    $ minicom -D <tty_device> -b 115200
 
 Replace :code:`<tty_device>` with the port where the nRF52840 SoC is connected
-to. Usually, under Linux it will be :code:`/dev/ttyACM1`. The `/dev/ttyACM0`
+to. Usually, under Linux it will be ``/dev/ttyACM1``. The ``/dev/ttyACM0``
 port is connected to the nRF9160 SiP on the board.
 
 Then build and flash the application in the usual way.

diff --git a/boards/x86/up_squared/doc/index.rst b/boards/x86/up_squared/doc/index.rst
@@ -326,13 +326,13 @@ Prepare Linux host
 #. Follow `Creating a GRUB2 Boot Loader Image from a Linux Host`_ steps
    to create grub binary.
 
-#. Install DHCP, TFTP servers. For example `dnsmasq`
+#. Install DHCP, TFTP servers. For example ``dnsmasq``
 
    .. code-block:: console
 
       $ sudo apt-get install dnsmasq
 
-#. Configure DHCP server. Configuration for `dnsmasq` is below:
+#. Configure DHCP server. Configuration for ``dnsmasq`` is below:
 
    .. code-block:: console
 
@@ -349,7 +349,7 @@ Prepare Linux host
       tftp-root=/srv/tftp
       dhcp-boot=grub_x86_64.efi
 
-   `grub_x86_64.efi` is a grub binary created above.
+   ``grub_x86_64.efi`` is a grub binary created above.
 
 #. Create the following directories inside TFTP root :file:`/srv/tftp`
 
@@ -391,7 +391,7 @@ Prepare Linux host
       └── kernel
           └── zephyr.strip
 
-#. Restart `dnsmasq` service:
+#. Restart ``dnsmasq`` service:
 
    .. code-block:: console
 

diff --git a/boards/xtensa/esp32/doc/index.rst b/boards/xtensa/esp32/doc/index.rst
@@ -149,7 +149,7 @@ Using JTAG
 
 As with much custom hardware, the ESP-32 modules require patches to
 OpenOCD that are not upstream.  Espressif maintains their own fork of
-the project here.  By convention they put it in the `~/esp` next to the
+the project here.  By convention they put it in ``~/esp`` next to the
 installations of their toolchain and SDK:
 
 .. code-block:: console

diff --git a/doc/application/index.rst b/doc/application/index.rst
@@ -302,8 +302,8 @@ into a single application image that can be run on simulated hardware or real
 hardware.
 
 As described in :ref:`getting_started_cmake`, on Linux and macOS you can choose
-between the `make` and `ninja` generators, whereas on Windows you need to use
-`ninja`. For simplicity we will use `ninja` throughout this guide.
+between the ``make`` and ``ninja`` generators, whereas on Windows you need to use
+``ninja``. For simplicity we will use ``ninja`` throughout this guide.
 
 Basics
 ======

diff --git a/doc/conf.py b/doc/conf.py
@@ -143,7 +143,15 @@
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
-#default_role = None
+
+# This change will allow us to use bare back-tick notation to let
+# Sphinx hunt for a reference, starting with normal "document"
+# references such as :ref:, but also including :c: and :cpp: domains
+# (potentially) helping with API (doxygen) references simply by using
+# `name`
+
+default_role = 'any'
+# default_domain = 'cpp'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
@@ -390,6 +398,13 @@
 }
 breathe_default_project = "Zephyr"
 
+# Changing breathe configuration to force "c" domain doesn't work
+# see https://github.com/michaeljones/breathe/issues/282
+#breathe_domain_by_extension = {
+#    "h" : "c",
+#    "c" : "c",
+#    }
+
 # Qualifiers to a function are causing Sphihx/Breathe to warn about
 # Error when parsing function declaration and more.  This is a list
 # of strings that the parser additionally should accept as

diff --git a/doc/contribute/index.rst b/doc/contribute/index.rst
@@ -265,10 +265,10 @@ gitlint
 
 When you submit a pull request to the project, a series of checks are
 performed to verify your commit messages meet the requirements. The same step
-done during the CI process can be performed locally using the the `gitlint`
+done during the CI process can be performed locally using the the ``gitlint``
 command.
 
-Run `gitlint` locally in your tree and branch where your patches have been
+Run ``gitlint`` locally in your tree and branch where your patches have been
 committed:
 
 .. code-block:: console

diff --git a/doc/development_process/release_process.rst b/doc/development_process/release_process.rst
@@ -249,11 +249,11 @@ Every time a release candidate (or the final release) needs to be tagged, the
 following steps need to be followed:
 
 #. Update the :zephyr_file:`VERSION` file in the root of the Git repository. If it's a
-release candidate, use `EXTRAVERSION` variable::
+release candidate, use ``EXTRAVERSION`` variable::
 
     EXTRAVERSION = rc1
 
-#. Commit the update to the :zephyr_file:`VERSION` file, use `release:` as a commit
+#. Commit the update to the :zephyr_file:`VERSION` file, use ``release:`` as a commit
    tag.
 #. Check that CI has completed successfully before tagging.
 #. Tag and push the version, using annotated tags:
@@ -280,18 +280,18 @@ release candidate, use `EXTRAVERSION` variable::
     $ git shortlog v1.10.0..v.1.11.0-rc1
 
 #. Find the new tag at the top of the releases page, edit the release with the
-   `Edit` button and then do the following:
+   ``Edit`` button and then do the following:
 
   * If it's a release candidate:
 
-    * Name it `Zephyr 1.11.0-rc1`
+    * Name it ``Zephyr 1.11.0-rc1``
     * Copy the shortlog into the release notes textbox (don't forget to quote it
       properly so it shows as unformatted text in Markdown)
     * Check the "This is a pre-release" checkbox
   * If it's a release:
 
-    * Name it `Zephyr 1.11.0`
-    * Copy the full content of `docs/release-notes-1.11.rst` into the the
+    * Name it ``Zephyr 1.11.0``
+    * Copy the full content of ``docs/release-notes-1.11.rst`` into the the
       release notes textbox
     * Copy the full list of GitHub issues closed with this release into the
       release notes textbox (see below on how to generate this list)

diff --git a/doc/getting_started/index.rst b/doc/getting_started/index.rst
@@ -51,7 +51,7 @@ shell or ``cmd.exe`` prompt:
 
 .. note::
    See :ref:`gs_python_deps` for additional clarfication on using the
-   `--user` switch.
+   ``--user`` switch.
 
 Additional information about west's structure can be found
 :ref:`in the relevant west documentation section <west-struct>`.

diff --git a/doc/guides/dts/index.rst b/doc/guides/dts/index.rst
@@ -375,7 +375,7 @@ extracted information should be formatted.
 
 A YAML description (called "YAML binding") must be provided for every device node
 that is a source of information for the system.  A YAML binding file
-is associated to each node `compatible` property.  Information within the YAML
+is associated to each node ``compatible`` property.  Information within the YAML
 file will instruct the python DTS parsing script (located in ``scripts/dts``) how
 each property of the node is expected to be generated, either the type of the
 value or the format of its name.  Node properties are generated as C-style

diff --git a/doc/guides/porting/arch.rst b/doc/guides/porting/arch.rst
@@ -300,7 +300,7 @@ mode if the thread triggered a fatal exception, but not if the thread
 gracefully exits its entry point function.
 
 This means implementing an architecture-specific version of
-:c:func:`k_thread_abort`, and setting the Kconfig option
+:cpp:func:`k_thread_abort`, and setting the Kconfig option
 :option:`CONFIG_ARCH_HAS_THREAD_ABORT` as needed for the architecture (e.g. see
 :zephyr_file:`arch/arm//core/cortex_m/Kconfig`).
 

diff --git a/doc/guides/test/ztest.rst b/doc/guides/test/ztest.rst
@@ -23,7 +23,7 @@ the **bar** component of **foo**, you should copy the sample folder to
 
 
 In the example above ``tests/foo/bar`` signifies the path to the test and the
-``test-identifier`` references a test defined in the file::`testcase.yaml` file.
+``test-identifier`` references a test defined in the :file:`testcase.yaml` file.
 
 To run all tests defined in a test project, run::
 

diff --git a/doc/reference/kernel/usermode/mpu_stack_objects.rst b/doc/reference/kernel/usermode/mpu_stack_objects.rst
@@ -7,7 +7,7 @@ Thread Stack Creation
 *********************
 
 Thread stacks are declared statically with :c:macro:`K_THREAD_STACK_DEFINE()`
-or embedded within structures using c:macro:`K_THREAD_STACK_MEMBER()`
+or embedded within structures using :c:macro:`K_THREAD_STACK_MEMBER()`
 
 For architectures which utilize memory protection unit (MPU) hardware,
 stacks are physically contiguous allocations.  This contiguous allocation

diff --git a/doc/reference/networking/mqtt.rst b/doc/reference/networking/mqtt.rst
@@ -92,7 +92,7 @@ used. An example configuration for TCP transport is shown below:
 
 After the configuration is set up, the MQTT client can connect to the MQTT broker.
 Call the ``mqtt_connect`` function, which will create the appropriate socket,
-establish a TCP/TLS connection, and send an `MQTT CONNECT` message.
+establish a TCP/TLS connection, and send an ``MQTT CONNECT`` message.
 When notified, the application should call the ``mqtt_input`` function to process
 the response received. Note, that ``mqtt_input`` is a non-blocking function,
 therefore the application should use socket ``poll`` to wait for the response.

diff --git a/doc/reference/networking/net_mgmt.rst b/doc/reference/networking/net_mgmt.rst
@@ -21,7 +21,7 @@ The Network Management API implementation is designed to save memory
 by eliminating code at build time for management routines that are not
 used. Distinct and statically defined APIs for network management
 procedures are not used.  Instead, defined procedure handlers are
-registered by using a `NET_MGMT_REGISTER_REQUEST_HANDLER`
+registered by using a :c:macro:`NET_MGMT_REGISTER_REQUEST_HANDLER`
 macro. Procedure requests are done through a single :cpp:func:`net_mgmt()` API
 that invokes the registered handler for the corresponding request.
 

diff --git a/doc/reference/shell/index.rst b/doc/reference/shell/index.rst
@@ -367,7 +367,7 @@ Usage
 *****
 
 To create a new shell instance user needs to activate requested
-backend using `menuconfig`.
+backend using ``menuconfig``.
 
 The following code shows a simple use case of this library:
 

diff --git a/doc/reference/storage/disk/sdhc.rst b/doc/reference/storage/disk/sdhc.rst
@@ -24,8 +24,8 @@ MMC and SDSC (<= 2 GiB) cards are not supported and will be ignored.
 Enabling
 ********
 
-For example, this device tree fragment adds an SDHC card slot on `spi1`,
-uses `PA27` for chip select, and runs the SPI bus at 24 MHz once the
+For example, this device tree fragment adds an SDHC card slot on ``spi1``,
+uses ``PA27`` for chip select, and runs the SPI bus at 24 MHz once the
 SDHC card has been initialized:
 
 .. code-block:: none

diff --git a/doc/releases/release-notes-1.10.rst b/doc/releases/release-notes-1.10.rst
@@ -86,7 +86,7 @@ Drivers and Sensors
 *******************
 
 * timer: Add Support for TICKLESS KERNEL in xtensa_sys_timer
-* Rename `random` to `entropy`
+* Rename ``random`` to ``entropy``
 * Add Atmel SAM I2S (SSC) driver
 * Add Atmel SAM DMA (XDMAC) driver
 * Add plantower PMS7003 Driver

diff --git a/doc/releases/release-notes-1.12.rst b/doc/releases/release-notes-1.12.rst
@@ -635,12 +635,12 @@ These GitHub issues were closed since the previous 1.11.0 tagged release:
 * :github:`7380` - dma_stm32f4x possible access out of bounds in start/stop handlers
 * :github:`7388` - nxp_mpu: suspicious ENDADDR_ROUND() macro
 * :github:`7389` - t1_adc108s102 buffer overflow due to chan->buf_idx growth
-* :github:`7412` - Mismatch between 'uint32_t' (and `off_t`) definitions in minimal libc and newlib
+* :github:`7412` - Mismatch between 'uint32_t' (and 'off_t') definitions in minimal libc and newlib
 * :github:`7434` - bluetooth: host: sample applications can't set BT address w/o using an FS
 * :github:`7437` - Zephyr's mailing list archives were hard to find
 * :github:`7442` - menuconfig should perform fuzzy string matching for symbols
 * :github:`7447` - net tests: valgrind detected issues
-* :github:`7452` - nRF52, NXP kinetis, ARM Beetle and  STM `MPU` option appear for every MPU-equipped device
+* :github:`7452` - nRF52, NXP kinetis, ARM Beetle and  STM MPU option appear for every MPU-equipped device
 * :github:`7453` - Bluetooth mesh message context API needs to expose DST address of RX messages
 * :github:`7459` - net: Multiple inconsistent settings to configure TIME_WAIT delay in the IP stack
 * :github:`7460` - Unable to view PR #6391
@@ -752,7 +752,7 @@ These GitHub issues were closed since the previous 1.11.0 tagged release:
 * :github:`7979` - drivers: dma: dma_cavs: DMA driver does not support per-channel callbacks
 * :github:`7989` - eth: ping: can't ping others from zephyr console
 * :github:`8005` - FRDM-K64F boot hang w/ mcuboot + lwm2m client
-* :github:`8009` - POSIX `clock_gettime()` is discontinuous
+* :github:`8009` - POSIX clock_gettime() is discontinuous
 * :github:`8015` - Driver:spi_flash_w25qxxdv.c init mistake and can not be erased
 * :github:`8032` - _SysFatalErrorHandler not working properly for arc on quark_se_c1000_ss_devboard
 * :github:`8033` - tests/crypto/mbedtls/ results in exception on frdm_k64f

diff --git a/doc/releases/release-notes-1.13.rst b/doc/releases/release-notes-1.13.rst
@@ -523,7 +523,7 @@ release:
 * :github:`8415` - [Coverity CID :186581] Memory - corruptions in /subsys/bluetooth/host/gatt.c
 * :github:`8414` - [Coverity CID :186582] Memory - corruptions in /subsys/bluetooth/host/gatt.c
 * :github:`8413` - [Coverity CID :186583] Error handling issues in /samples/net/sockets/dumb_http_server/src/socket_dumb_http.c
-* :github:`8393` - `CONFIG_MULTITHREADING=n` builds call `main()` with interrupts locked
+* :github:`8393` - ``CONFIG_MULTITHREADING=n`` builds call main() with interrupts locked
 * :github:`8391` - nrf52_blenano2 tmp112 sensor sample build failed.
 * :github:`8390` - bluetooth: request APIs to notify application that pairing is complete or not
 * :github:`8388` - Assigning to promptless symbols should have a better error message
@@ -535,7 +535,7 @@ release:
 * :github:`8367` - fs: nvs: auto restore FS on writing while power down error.
 * :github:`8366` - mcumgr: unable to perform 2nd update
 * :github:`8365` - mcumgr: improper response to "image list" command after update.
-* :github:`8361` - __ASSERT() triggers with `CONFIG_MULTITHREADING=n`
+* :github:`8361` - __ASSERT() triggers with ``CONFIG_MULTITHREADING=n``
 * :github:`8358` - Flashing Target Device FAIL
 * :github:`8357` - bluetooth: request the capability to change gap device name programmatically
 * :github:`8356` - Failed test: kernel.common.bitfield (tests/kernel/common) on Altera Max10

diff --git a/samples/boards/96b_argonkey/sensors/README.rst b/samples/boards/96b_argonkey/sensors/README.rst
@@ -23,7 +23,7 @@ The user may select or unselect the sensors from
 :zephyr_file:`samples/boards/96b_argonkey/sensors/prj.conf`.
 
 Please note that all sensor related code is conditionally compiled
-using the `#ifdef` directive, so this sample is supposed to always
+using the ``#ifdef`` directive, so this sample is supposed to always
 build correctly. Example:
 
 .. code-block:: c

diff --git a/samples/gui/lvgl/README.rst b/samples/gui/lvgl/README.rst
@@ -23,12 +23,12 @@ or a simulated display environment in a native Posix application:
 or
 
 - :ref:`mimxrt1050_evk`
-- `RK043FN02H-CT`
+- `RK043FN02H-CT`_
 
 or
 
 - :ref:`mimxrt1060_evk`
-- `RK043FN02H-CT`
+- `RK043FN02H-CT`_
 
 Wiring
 ******

diff --git a/samples/net/sockets/big_http_download/README.rst b/samples/net/sockets/big_http_download/README.rst
@@ -8,7 +8,7 @@ Overview
 
 The sockets/big_http_download sample application for Zephyr implements
 a simple HTTP GET client using a BSD Sockets compatible API. Unlike
-the `sockets-http-get` sample application, it downloads a file of
+the :ref:`sockets-http-get` sample application, it downloads a file of
 several megabytes in size, and verifies its integrity using hashing. It
 also performs download repeatedly, tracking the total number of bytes
 transferred. Thus, it can serve as a "load testing" application for

diff --git a/samples/subsys/mgmt/mcumgr/smp_svr/README.rst b/samples/subsys/mgmt/mcumgr/smp_svr/README.rst
@@ -25,7 +25,7 @@ This sample application supports the following mcumgr transports by default:
 Caveats
 *******
 
-* The Zephyr port of `smp_svr` is configured to run on a Nordic nRF52x MCU. The
+* The Zephyr port of ``smp_svr`` is configured to run on a Nordic nRF52x MCU. The
   application should build and run for other platforms without modification, but
   the file system management commands will not work.  To enable file system
   management for a different platform, adjust the