Update example documentation

Updates the Example Application's document to use the sphinx-ncs-theme v0.7.4, which was the latest version I could get to easily work. Also adds some example pages and documentation guidance. Signed-off-by: Wille Backman <[email protected]>
nrfconnect · Sep 25, 2024 · 178e48c · 178e48c
1 parent 1f0170f
commit 178e48c
Show file tree

Hide file tree

Showing 11 changed files with 197 additions and 22 deletions.
diff --git a/doc/about.rst b/doc/about.rst
@@ -0,0 +1,78 @@
+.. _example_about:
+
+About the Example Application
+#############################
+
+.. contents::
+   :local:
+   :depth: 2
+
+The About page is where more detailed information about the application should be placed.
+For this example, it contains information on the documentation structure.
+
+Table of contents
+*****************
+
+When a page other than the landing page is long and contains headers, you should also add a table of contents to that page.
+To generate the table of contents, add the following after the page title:
+
+.. code-block:: RST
+
+  .. contents::
+     :local:
+     :depth: 2
+
+.. _example_about_naming:
+
+Naming page files and page links
+********************************
+
+When naming the file for a page, use simple and descriptive names.
+Keep in mind that the file name will also be visible in the URL.
+
+You should attach a reference target to every every page title as well.
+The reference target is used when linking from one page to another.
+In most cases, it's good to match the reference target to the page name, as this makes it easier to know which page is linked when the target is used.
+For example, the the reference target for this page is ``example_about``, and it is defined with the following line just before the page title:
+
+.. code-block:: RST
+
+   .. _example_about:
+
+If you want to link to a subheading on a page, you should also add a reference target for that heading.
+The best practice for naming subheading reference targets is to use the page reference target and add some or all of the heading.
+For example, the reference target for this section is ``example_about_naming``, and it is defined in the same way as the page reference target.
+
+When you want to link to a reference target, you can use either of the following:
+
+.. code-block:: RST
+
+   :ref:`example_about`
+   :ref:`replaced link text <example_about>`
+
+The first one uses the name of the heading or title that is linked (:ref:`example_about`), while the second one replaces that with a custom link text (:ref:`replaced link text <example_about>`).
+
+External links
+==============
+
+For links outside of the documentation set, use the :file:`links.txt` file.
+This file makes it easier to update and re-use links.
+Define the links according to the existing examples, then use either of the following to place the link in the text:
+
+.. code-block:: RST
+
+   `nRF Connect SDK`_
+   `replaced link text <nRF Connect SDK_>`_
+
+The first one uses the name of the link (`nRF Connect SDK`_), while the second one replaces that with a custom link text (`replaced link text <nRF Connect SDK_>`_).
+
+Recommended pages
+*****************
+
+In addition to the About page, the following pages are recommended for all applications.
+
+Requirements and setup
+   The :ref:`example_setup` details what the user needs to have so they can work with the application.
+
+Release notes
+   The release notes page documents changes for each release.
diff --git a/doc/conf.py b/doc/conf.py
@@ -7,8 +7,8 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'NCS Example Application'
-copyright = '2024, The Zephyr Community'
-author = 'The Zephyr Community'
+copyright = '2024, Nordic Semiconductor'
+author = 'Nordic Semiconductor'
 release = '1.0.0'
 
 # -- General configuration ---------------------------------------------------
@@ -22,7 +22,7 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'alabaster'
+html_theme = 'sphinx_ncs_theme'
 
 ## -- Options for Breathe ----------------------------------------------------
 # https://breathe.readthedocs.io/en/latest/index.html
@@ -33,3 +33,8 @@
 breathe_projects = {'ncs-example-application': '_build_doxygen/xml'}
 breathe_default_project = 'ncs-example-application'
 breathe_default_members = ('members', )
+
+# Include following files at the end of each .rst file.
+rst_epilog = """
+.. include:: /links.txt
+"""
diff --git a/doc/drivers/blink.rst b/doc/drivers/blink.rst
@@ -1,14 +1,16 @@
+.. _example_driver_blink:
+
 Blink
-=====
+#####
 
 .. doxygengroup:: drivers_blink
 
 Driver operations
------------------
+*****************
 
 .. doxygengroup:: drivers_blink_ops
 
 Public API
-----------
+**********
 
 .. doxygengroup:: drivers_blink_api
diff --git a/doc/drivers/index.rst b/doc/drivers/index.rst
@@ -1,9 +1,13 @@
+.. _example_drivers:
+
 Drivers
-=======
+#######
+
+This is an example for documenting drivers.
 
 .. doxygengroup:: drivers
 
 .. toctree::
-    :maxdepth: 1
+   :maxdepth: 1
 
-    blink
+   blink
diff --git a/doc/index.rst b/doc/index.rst
@@ -1,17 +1,19 @@
+.. _exaple_index:
+
 Welcome to NCS Example Application's documentation!
-===================================================
+###################################################
 
 This is a simple Sphinx documentation setup for ``ncs-example-application``.
+You can use this as a template for your own application's documentation.
+
+This landing page should be a brief description what the application does, but does not need to go into full detail.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents
 
+   about
+   setup
    drivers/index
    lib/index
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`
+   release-notes
diff --git a/doc/lib/custom.rst b/doc/lib/custom.rst
@@ -1,11 +1,13 @@
+.. _example_lib_custom:
+
 Custom
-======
+######
 
 .. doxygengroup:: lib_custom
     :desc-only:
 
 Public API
-----------
+**********
 
 .. doxygengroup:: lib_custom
-    :content-only:
+    :content-only:
diff --git a/doc/lib/index.rst b/doc/lib/index.rst
@@ -1,9 +1,13 @@
+.. _example_lib:
+
 Libraries
-=========
+#########
+
+This is an example for documenting libraries.
 
 .. doxygengroup:: lib
 
 .. toctree::
-    :maxdepth: 1
+   :maxdepth: 1
 
-    custom
+   custom
diff --git a/doc/links.txt b/doc/links.txt
@@ -0,0 +1,7 @@
+.. ### nRF Connect SDK documentation
+
+.. _`nRF Connect SDK`: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/index.html
+.. _`Installing the nRF Connect SDK`: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/installation/install_ncs.html
+
+.. _`Known issues for the nRF Connect SDK`: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/releases_and_maturity/known_issues.html
+.. _`Release notes for the nRF Connect SDK`: https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/releases_and_maturity/release_notes.html
diff --git a/doc/release-notes.rst b/doc/release-notes.rst
@@ -0,0 +1,34 @@
+.. _example_release_notes:
+
+Release notes
+#############
+
+.. contents::
+   :local:
+   :depth: 2
+
+All the notable changes to this application are listed here.
+
+To follow the nRF Connect SDK style for release notes, group entries for Added, Changed, and Removed under a single bullet.
+
+.. _example_release_xx:
+
+Example Application - vX.X
+**************************
+
+* Changed:
+
+  * Feature two to handle both something and another function.
+  * Feature one to do a completely different thing.
+
+.. _example_release_xy:
+
+Example Application - vX.Y
+**************************
+
+* Added:
+
+  * Feature one, which is used to do something.
+  * Feature two, which is used for another function.
+
+* Removed feature three.
diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -1,2 +1,3 @@
 Sphinx
 breathe
+sphinx-ncs-theme==0.7.4
diff --git a/doc/setup.rst b/doc/setup.rst
@@ -0,0 +1,36 @@
+.. _example_setup:
+
+Requirements and setup
+######################
+
+This page outlines the requirements that you need to meet before you start working with [application/technology].
+
+If extensive information is required, create a Setting up [application] page instead, with sub pages for requirements and setting up different parts.
+See the `Setting up the Sidewalk environment`_ page of the nRF Connect SDK Amazon Sidewalk documentation for an example.
+
+Hardware requirements
+*********************
+
+To work with [application/technology], you need one/two of the following:
+
+* link to device product page
+* link to device product page
+
+Add any additional information on the devices after the list.
+
+If the user needs a smartphone or tablet to run an app, mention it both here and in the software requirements.
+
+List any optional devices last.
+
+Software requirements
+*********************
+
+To work with [application/technology], you need to install [link to application].
+
+If there are options, make a bullet list for those options.
+
+List any optional software last.
+
+If there are additional instructions on how the user needs to install or configure the software, create a subheading with the software's name and add the information there.
+
+.. _`Setting up the Sidewalk environment`: https://docs.nordicsemi.com/bundle/sidewalk_latest/page/setting_up_sidewalk_environment/setting_up_hardware.html