Basic guides information

Signed-off-by: Cristian Le <[email protected]>

docs/conf.py

@@ -29,20 +29,25 @@
     "tasklist",
     "colon_fence",
 ]
+myst_heading_anchors = 3
 
 intersphinx_mapping = {
     "cmake": ("https://cmake.org/cmake/help/latest", None),
     "sphinx": ("https://www.sphinx-doc.org/en/master", None),
     "rtd": ("https://docs.readthedocs.io/en/stable", None),
     "tmt": ("https://tmt.readthedocs.io/en/stable", None),
+    "sphinx-tippy": ("https://sphinx-tippy.readthedocs.io/en/latest", None),
+    "sphinx-hoverxref": ("https://sphinx-hoverxref.readthedocs.io/en/latest", None),
 }
 
 tippy_rtd_urls = [
     ## Only works with RTD hosted intersphinx
     # "https://cmake.org/cmake/help/latest",
-    # "https://www.sphinx-doc.org/en/master",
+    "https://www.sphinx-doc.org/en/master",
     "https://docs.readthedocs.io/en/stable",
     "https://tmt.readthedocs.io/en/stable",
+    "https://sphinx-tippy.readthedocs.io/en/latest",
+    "https://sphinx-hoverxref.readthedocs.io/en/latest",
 ]
 
 copybutton_exclude = ".linenos, .gp, .go"

docs/guides/developer/index.md

@@ -1,5 +1,15 @@
 # Developer guide
 
+```{toctree}
+---
+maxdepth: 2
+titlesonly: true
+hidden: true
+glob: true
+---
+who-is-the-developer
+```
+
 This is a developer's guide intended to explain many of the paradigms used in
 this template project
 

docs/guides/developer/who-is-the-developer.md

@@ -0,0 +1,11 @@
+# Who is the developer?
+
+In the context of this guide, the developer is someone who:
+- is looking to expand the build system to add more options, expand the project
+  dependencies
+- a project developer who is looking at implementing this template project
+- a CMake enthusiast looking for a common standard for their design. (Feel free
+  to interact in the template [issue page] if you have any comments)
+- a non-CMake build-system enthusiast. There is no discrimination here :)
+
+[issue page]: https://github.com/LecrisUT/CMake-Template/issues

docs/guides/index.md

@@ -4,8 +4,86 @@
 ---
 maxdepth: 2
 titlesonly: true
-caption: Guides
-glob: true
 ---
-*/index
+user/index
+developer/index
 ```
+
+## 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.
+
+[user]: user/who-is-the-user.md
+[developer]: developer/who-is-the-developer.md
+[user guide]: user/index.md
+[developer guide]: developer/index.md
+[include]: #including-these-guides-in-your-downstream-project
+
+## Including these guides in your downstream project
+
+The best way to include these guides is if your project uses a
+[sphinx backend][rtd-sphinx] 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:
+
+```{code-block} python
+---
+caption: docs/conf.py
+emphasize-lines: 5
+---
+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][sphinx-hoverxref-issue].
+:::
+
+Then, you can use it in your documentation files as follows:
+
+::::{tab-set}
+:::{tab-item} Markdown
+```{code-block} markdown
+---
+caption: docs/example.md
+emphasize-lines: 4
+---
+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
+```
+:::
+:::{tab-item} reStructuredText
+```{code-block} rst
+---
+caption: docs/example.rst
+emphasize-lines: 1
+---
+Refer to the :external+template-user-guide:std:doc:`following guide<template-user-guide>`
+for a basic how-to interact with a CMake project...
+```
+:::
+:::{tab-item} (Result)
+Refer to the [following guide][user guide] for a basic how-to interact with a
+CMake project...
+:::
+::::
+
+[rtd-sphinx]: inv:rtd:std:doc#intro/getting-started-with-sphinx
+[//]: # (TODO: Fix the intersphinx link)
+[inter-sphinx]: https://www.sphinx-doc.org/en/master/usage/quickstart.html#intersphinx
+[`sphinx-tippy`]: inv:sphinx-tippy#index
+[`sphinx-hoverxref`]: inv:sphinx-hoverxref#index
+[sphinx-hoverxref-issue]: https://github.com/readthedocs/sphinx-hoverxref/issues/250

docs/guides/user/index.md

@@ -1,6 +1,23 @@
 # User guide
 
+```{toctree}
+---
+maxdepth: 2
+titlesonly: true
+hidden: true
+glob: true
+---
+who-is-the-user
+```
+
 This is a general guide for how a user can interact with modern CMake project
-that follows such a template
+that follows such a template.
+
+This guide will walk you through all the steps that the user would typically
+follow from how to get the project they are interested in, to how to install it
+for day-to-day usage.
+
+For quick links and tl;dr questions, see the following section, otherwise
+consider navigating the guide step-by-step.
 
-**Coming soon**
+## tl;dr

docs/guides/user/who-is-the-user.md

@@ -0,0 +1,69 @@
+# Who is the user?
+
+## Not the end-user
+
+The end-user of the project should not have to build the project directly using
+CMake, not even if the project is a library that is meant to be used by other
+downstream projects. For these situations the user should have access to
+packaged versions of the project (Fedora, PyPI, homebrew package etc.) See
+the [developer guide] on how to set it up.
+
+[developer guide]: ../developer/index.md
+
+## User interacting with CMake
+
+For the context of this guide, we are focusing on the user who would actually
+have to interact with CMake. Each kind of users will have different level of
+familiarity with CMake and needs for using it. Throughout this guide there will
+be relevant notes that are particularly important to a subset of people, e.g.:
+
+[//]: # (TODO: Is it possible to link the tab-item back to this page?)
+
+> #### How do I configure the project?
+> ::::{tab-set}
+> :::{tab-item} As an end-user
+> Here is the most basic instructions
+> :::
+> :::{tab-item} As an upstream developer
+> Here is how you can make your life easier
+> :::
+> :::{tab-item} As a downstream packager
+> Beware of the packaging guidelines
+> :::
+> ::::
+
+### End-user
+
+Ok, I've lied, there are situations when the end-user would need to build the
+project from source, e.g. when the packaged project does not include the
+features you need. Nevertheless, even here the user will have a bare minimum
+interaction with CMake, and it is assumed they will not have to interact with it
+(at least in the context of building your project) after this.
+
+### Upstream developer
+
+Here the upstream developer refers to the day-to-day developer of the current
+project that uses this guide's template. Other developers that would be
+importing the current project are considered to be an [end user].
+
+This type of developer would not be handling the build-system, the project CI,
+or any other bells-and-whistles that are implemented with this template.
+Instead, their main goal is to maintain the main C/C++ (or other language) code.
+
+### Packager
+
+The final type of user of this guide is the rarest, of them all, and they should
+be having the most experience with CMake itself. Nevertheless, there are a few
+nuances that they should be aware of regarding the modern CMake design
+implemented here.
+
+Even so, in this guide, I will not be assuming any prior CMake expertise, even
+when the sections are aimed primarily for this group of people, and hopefully at
+the end of this guide, you should be able to interact with any CMake project
+old-or-new, in any packaging environment. I will not be explaining much of the
+CMake inner-workings more than it is relevant, and if you are interested in that
+check the [developer guide] as well.
+
+[end user]: #end-user
+[developer]: #upstream-developer
+[packager]: #packager