Guides#

What are these guides?#

In this template project, you will find a user guide and a developer guide intended to answer common questions that either a user or a developer would have when encountering a project that uses this template.

Feel free to reference and/or include these guides or sections of it in your documentation.

Including these guides in your downstream project#

The best way to include these guides is if your project uses a sphinx backend for your documentation. There you can simply link to it using inter-sphinx. For example, include the following configurations to your docs/conf.py file:

docs/conf.py#
extensions = [
    "sphinx.ext.intersphinx",
]
intersphinx_mapping = {
    "template-guide": ("https://lecrisut-cmake-template.readthedocs.io/en/latest/", None),
}

Note

If you want to have the links pop-up like in this documentation, use either sphinx-tippy or sphinx-hoverxref. The latter produces better results, however it does not yet support Markdown documents.

Then, you can use it in your documentation files as follows:

docs/example.md#
Refer to the [following guide][template-user-guide] for a basic how-to interact
with a CMake project...

[template-user-guide]: inv:template-user-guide:std:doc#guides/user/index
docs/example.rst#
Refer to the :external+template-user-guide:std:doc:`following guide<template-user-guide>`
for a basic how-to interact with a CMake project...

Refer to the following guide for a basic how-to interact with a CMake project…