From 178e48c46629d1923d85e37f332d0a8cf2daf6bf Mon Sep 17 00:00:00 2001 From: Wille Backman Date: Wed, 25 Sep 2024 13:33:52 +0300 Subject: [PATCH] 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 --- doc/about.rst | 78 +++++++++++++++++++++++++++++++++++++++++++ doc/conf.py | 11 ++++-- doc/drivers/blink.rst | 8 +++-- doc/drivers/index.rst | 10 ++++-- doc/index.rst | 16 +++++---- doc/lib/custom.rst | 8 +++-- doc/lib/index.rst | 10 ++++-- doc/links.txt | 7 ++++ doc/release-notes.rst | 34 +++++++++++++++++++ doc/requirements.txt | 1 + doc/setup.rst | 36 ++++++++++++++++++++ 11 files changed, 197 insertions(+), 22 deletions(-) create mode 100644 doc/about.rst create mode 100644 doc/links.txt create mode 100644 doc/release-notes.rst create mode 100644 doc/setup.rst diff --git a/doc/about.rst b/doc/about.rst new file mode 100644 index 0000000..7c359bb --- /dev/null +++ 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 ` + +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 `). + +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 `_ + +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 `_). + +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 index 0da4fc4..738f304 100644 --- 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 index 8f67edf..f94e0d8 100644 --- 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 index a287e41..d104185 100644 --- 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 index 79dd6af..4af9ef0 100644 --- 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 index b2261ef..93293e4 100644 --- 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: \ No newline at end of file + :content-only: diff --git a/doc/lib/index.rst b/doc/lib/index.rst index 1e46b5a..65f93a2 100644 --- 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 new file mode 100644 index 0000000..0b378e8 --- /dev/null +++ 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 new file mode 100644 index 0000000..5e8c512 --- /dev/null +++ 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 index 7f36028..89cee5f 100644 --- 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 new file mode 100644 index 0000000..091e718 --- /dev/null +++ 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