From 621ae2136188d0162f00d4c7fdb48a80526d535f Mon Sep 17 00:00:00 2001 From: Cristian Le Date: Mon, 18 Dec 2023 20:18:25 +0100 Subject: [PATCH] Basic guides information Signed-off-by: Cristian Le --- docs/conf.py | 7 +- docs/guides/developer/index.md | 10 +++ docs/guides/developer/who-is-the-developer.md | 11 +++ docs/guides/index.md | 84 ++++++++++++++++++- docs/guides/user/index.md | 21 ++++- docs/guides/user/who-is-the-user.md | 69 +++++++++++++++ 6 files changed, 196 insertions(+), 6 deletions(-) create mode 100644 docs/guides/developer/who-is-the-developer.md create mode 100644 docs/guides/user/who-is-the-user.md diff --git a/docs/conf.py b/docs/conf.py index 04a8d80..f8c5876 100644 --- a/docs/conf.py +++ b/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" diff --git a/docs/guides/developer/index.md b/docs/guides/developer/index.md index 2346b1d..235f1b1 100644 --- a/docs/guides/developer/index.md +++ b/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 diff --git a/docs/guides/developer/who-is-the-developer.md b/docs/guides/developer/who-is-the-developer.md new file mode 100644 index 0000000..3877f23 --- /dev/null +++ b/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 diff --git a/docs/guides/index.md b/docs/guides/index.md index ce64715..0314ac2 100644 --- a/docs/guides/index.md +++ b/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` +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 diff --git a/docs/guides/user/index.md b/docs/guides/user/index.md index 8826d75..43e1935 100644 --- a/docs/guides/user/index.md +++ b/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 diff --git a/docs/guides/user/who-is-the-user.md b/docs/guides/user/who-is-the-user.md new file mode 100644 index 0000000..4f21bb9 --- /dev/null +++ b/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