.. Copyright 2023 CMakePP .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. .. You may obtain a copy of the License at .. .. http://www.apache.org/licenses/LICENSE-2.0 .. .. Unless required by applicable law or agreed to in writing, software .. distributed under the License is distributed on an "AS IS" BASIS, .. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. .. See the License for the specific language governing permissions and .. limitations under the License. ******************* Documenting CMakePP ******************* For the most part documentation in the CMakePP project falls into one of two categories: API or narrative. The following sections describe the conventions associated with these types. Many of the conventions rely on reStructuredText (reST) so the reader may find `this `_ reST primer to be of use. .. note:: I presume there's actually a real computer science term for "narrative documentation"; however, my Google-ing did not manage to find it so I'm using "narrative documentation" as a placeholder for it. If you know the real term please open an issue on the CMakeDev repo so that the documentation can be updated. API Documentation ================= API documentation tells you how to use a function, what a variable is for, or what a class models. Maintaining good API documentation is a key aspect of ensuring CMakePP is user-friendly. API documentation should not be used for prolonged discussions of the inner workings of a function or algorithm (such things should be documented, but fall under narrative documentation). For the most part source code associated with CMakePP is written in one of two languages, Python or CMake, and the following subsections describe the conventions for documenting APIs in each of those languages in detail. Python ------ Python has community accepted standards for documentation. Those standards are available in the `Python's developer guide `_. The main points are: - No more than 80 characters on a line - Indents are 3 spaces, not 4, and not tabs - Comments use restructured text (reST) The standard does not however strictly specify the contents of the documentation or the format of the comments. At the moment, Sphinx is the *de facto* tool for creating Python documentation from comments and we thus choose to follow `Sphinx's standards `_. To summarize this style, positional arguments are documented like: .. code-block:: rst :param arg1: description of arg2 :type arg1: type of arg1 variadic arguments like: .. code-block:: rst :param *args: description of the variadic arguments :type *args: The type(s) of the variadic arguments and returns are documented like: .. code-block:: rst :return: description of what is returned :rtype: The type of the returned object It should be noted that Python functions which return multiple values do so in a tuple, so the correct documentation for a multiple-return value function is: .. code-block:: python def my_mr_fxn(): """ Function which returns multiple values. :return: Two of the most overused values in documentation. :rtype: tuple(int, str) """ return 42, 'Hello World' I have not been able to find a standardized way of documenting kwargs; however, one "hack" I've come across that produces something that looks like the other aspects of the function's API is: .. code-block:: rst :param **kwargs: See below :Keyword Arguments: * *kwarg1* (``type``) -- description * *kwarg2* (``type``) -- description basically you have to manually make the kwargs section match the sections auto-generated by Sphinx. CMake ----- CMake documentation uses the ``CMakeDoc`` tool developed by the CMakePP project. This tool looks for specially prefixed CMake comments (line comments that start with ``##`` and block comments that start with ``#[[[``) and extracts the contents verbatim as documentation of the API/variable that the comment immediately proceeds. The contents of the comment are assumed to be reST and it is assumed that the documentation will be built using Sphinx. Therefore, we adopt the same reST standards as we do for Python with the following exceptions. Whereas global variables are frowned upon in Python they are unfortunately somewhat common in CMake. To document the global variables your function uses the syntax is: .. code-block:: rst :var GLOBAL_VARIABLE: Description of global variable :vartype GLOBAL_VARIABLE: type of the value stored in the global variable Narrative Documentation ======================= Narrative documentation is like the page you are currently reading. It is only loosely tied to a particular piece of code. Narrative documentation is meant for providing overviews, background information, implementation details, etc. Narrative documentation is built with Sphinx and is written using Sphinx-flavored reST. Consequentially many of the reST conventions from the API Documentation section carry over. Compared to writing reST API documentation the biggest difference when writing narrative documentation is that narrative documentation is typically partitioned into parts, chapters, sections, etc. While reST doesn't particularly care what characters you use to distinguish between headings for parts, chapters, sections, etc. it is very common practice (stemming from Python's documentation conventions) to obey: - ``#`` with overline for part headings - We also use this for the package name on the main ``index.rst`` - ``*`` with overline for chapter headings - ``=`` for sections - ``-`` for subsections - ``^`` for subsubsections - ``"`` for paragraphs - and you should seriously reevaluate your documentation if you need anything beyond that... The distinction between what constitutes a part, chapter, etc. is a bit fuzzy, but the general idea is that as you nest titles you rotate through the various characters. Typically what this means is that you'll use ``#`` for titles on ``index.rst`` pages, ``*`` for titles of pages included from ``index.rst`` pages, and ``=``, ``-``, and ``^`` respectively for sections, subsections, and subsubsections in the page included from the ``index.rst`` file.