Skip to content

Add `ocpi_documentation_include` directive to ocpidoc

Sam requested to merge o3281/opencpi:add-ocpidoc-include-directive into develop

What this MR does / why we need it:

This merge requests adds a custom include directive to ocpidoc that behaves similar to the Sphinx ".. include" directive but also allows for "find and replace" functionality. Ultimately this enables figure and equation numbering in included common documentation without Sphinx complaining about label duplication.

An example of the directive's use is shown below:

   .. ocpi_documentation_include:: ../common/shared_section.inc

      |component_name|: polyphase_clock_synchroniser_xs
      |path_to_figures|: ../common/

Which allows content like the following, within the included file:

   This problem is shown in :numref:`|component_name|-sampling-points-diagram` below.

   .. _|component_name|-sampling-points-diagram:

   .. figure:: |path_to_figures|symbol_sampling_points.svg
      :alt: Symbol Sampling Points.
      :align: center

      Symbol Sampling Points

Steps to complete before submitting MR:

  • I have read Contribution guidelines

  • I have ensured I have a changelog written in the imperative form that is meaningful and accurately summarizes the work done

  • I have added the release notes label if applicable (more information below)

  • I have ensured the workflow labels are up to date and will continue to do so up until this work is merged into develop

  • I have added a category, type, and target release label along with all other labels as need be

  • My branch is up to date with develop. If it is not, then I have ensured my work does not conflict with other work

  • I agree my bugfix MR does not include new features/enhancements

  • I represent that bugfixes have been locally tested against the most recent major.minor release in which the bug exists

  • (REVIEWER ONLY) I have thoroughly gone through the above steps to ensure that they have been followed

Release Notes

N/A

Changelog

  • enh(tools,documentation): add ocpi_documentation_include directive to ocpidoc

Which issue(s) this MR closes

N/A

Edited by Sam

Merge request reports